グローバルパラメーター

2020.03.19 2020.03.20

TOPICS

翻訳元記事はこちらです。

APIには、いくつかグローバルパラメーターが含まれます。
グローバルパラメーターは、APIがリクエストとレスポンスをどう扱うかコントロールします。この操作は、上の階層で行われて、すべてのリソースで利用可能です。

_fields

PostのようなRESTのリソースは、内容、タイトル、作者IDなどの基本情報などといった、大量のデータを含んでいます。
しかし、メディアなどのメタデータも持っています。アプリケーションを作成する際に、すべてのリクエストでこの情報を取得する必要はありません。

必要なフィールドだけ返すようにするには、_fieldsクエリーパラメーターを使用してください。
例えば、アーカイブのビューを作成するときに、ID、タイトル、パーマリンク、作者、抜粋文が必要な場合、fieldsのクエリーパラメーターを使用して制限することができます。

/wp/v2/posts?_fields=author,id,excerpt,title,link

コンマで区切らずに、配列の構文を使ってパラメーターを指定することもできます。

/wp/v2/posts?_fields[]=author&_fields[]=id&_fields[]=excerpt&_fields[]=title&_fields[]=link

_fieldsクエリーパラメーターが指定されたときには、必要ないフィールドはレスポンスには含まれません。
不必要なデータを取ってくるための処理を避けることができます。
JSONで返ってくるデータも少なくなり、ダウンロードの時間が短縮でき、クライアントのデバイスでの解析時間も短くできます。

各リソースから必要なプロパティのみを取得するようにクエリを慎重に設計することによって、アプリケーションを高速にできます。

WordPress 5.3以降では、_fieldsパラメーターは、ネストしたプロパティもサポートしています。
たくさんのメタキーを登録しているときに、役立つことがあります。
登録されたメタプロパティの１つだけの値をリクエストすることを許可します。

?_fields=meta.one-of-many-keys

上記の例では、one-of-many-keysのみ返して、その他は除かれます。

複雑なメタオブジェクトの深いネストの値を取得することもできます。

?_fields=meta.key_name.nested_prop.deeply_nested_prop,meta.key_name.other_nested_prop

_embed

ほとんどのリソースは、関連したリソースへのリンクを含んでいます。例えば、postは親投稿のリンクや、コメントにリンクできます。
HTTPリクエストの回数を減らすために、クライアントはリンクされたリソースと同様にリソースを取得したいと思うでしょう。
_embedパラメーターは、レスポンスに指定されたデータを含むように指示できます。

埋め込みのモードは、_embedパラメーターがクエリストリング（GETパラメーターとして）で渡されたときに使えるようになります。
このパラメーターは、値を必要としませんが、クライアントライブラリで必要な場合には「1」を渡すことができます。

未来の互換性のために、他の値は渡さないでください。

embedモードのリソースは、_embeddedキーと、リンクされたリソースを含む_linksキーを含むようになります。
リンクするだけの場合は、embeddableパラメーターにtrueをセットしてください。

リンクと埋め込みについてさらに情報が必要な場合は、リンクと埋め込みページを参照してください。

_method (or X-HTTP-Method-Override header)

サーバーやクライアントの中には、APIが活用するHTTPメソッドを正しく処理できないものもあります。
例えば、削除するリクエストでは、DELETEメソッドを使用しますが、DELETEメソッドを送信できないクライアントもあります。

このような場合のために、APIはメソッドのオーバーライドをサポートしています。
_methodパラメーターか、X-HTTP-Method-Overrideヘッダーに、使いたいHTTPメソッドをセットすることによって実現できます。

クライアントはPOSTリクエストでのみ、パラメーターかヘッダーをオーバーライドすべきです。GETリクエストで使用すると、間違ってキャッシュされる可能性があります。

POSTで送信される/wp-json/wp/v2/posts/42?_method=DELETEは、DELETEのwp/v2/posts/42ルートに変換されます。

同樣に以下のPOSTリクエストもDELETEに変換されます。

POST /wp-json/wp/v2/posts/42 HTTP/1.1
Host: example.com
X-HTTP-Method-Override: DELETE

_envelope

_methodパラメーター同樣に、サーバー、クライアント、プロキシの中には、すべてのレスポンスデータへのアクセスを許可していないものもあります。
APIは、_envelopeパラメーターを渡すことによって、headerとステータスコードを含むbodyで、すべてのレスポンスデータを渡すことをサポートします。

Envelopeモードは、_envelopeパラメーターをクエリストリングに含めると有効になります。（GETパラメーターで使用してください。）
このパラメーターは、値を必要としません。（?_envelopeだけでOKです）しかし、クライアントライブラリーによっては、”1″を値として必要とする場合もあります。

未来の互換性のために、他の値は渡さないでください。

Envelopedのレスポンスは、追加のヘッダーもなく、”偽の”200レスポンスを含みます。（Content-Typeとは別に）レスポンスが中継ぎを通して正しいものであることを確認してください。

例えば、wp/v2/users/meのGETリクエストに、以下のようなレスポンスを渡す場合。

HTTP/1.1 302 Found
Location: http://example.com/wp-json/wp/v2/users/42
 
{
  "id": 42,
  ...
}

envelopedモードのレスポンスは、以下のようになります。

HTTP/1.1 200 OK
 
{
  "status": 302,
  "headers": {
    "Location": "http://example.com/wp-json/wp/v2/users/42"
  },
  "body": {
    "id": 42
  }
}

_jsonp

APIは、古いブラウザーとクライアントでも、クロスドメインリクエストを許可するために、JSONPレスポンスをサポートしています。
このパラメーターは、データに付与されるJavaScriptのコールバック関数を必要とします。このURLは、<script>タグを通してロードされます。

コールバック関数は、英数字、アンダーバー、ピリオドの文字列を含むことができます。
許容できない文字列が含まれたときに、コールバック関数は、400エラーのレスポンスを受け取り、コールバックは呼ばれません。

モダンブラウザは、CORSを使用できます。しかし、JSONPを使うことによって、古いブラウザも含めて、すべてのブラウザをサポートすることができます。

例：

<script>
function receiveData( data ) {
  // Do something with the data here.
  // For demonstration purposes, we'll simply log it.
  console.log( data );
}
</script>
<script src="https://example.com/wp-json/?_jsonp=receiveData"></script>