このドキュメントでは、アプリケーションのパフォーマンスを向上させるためのテクニックをいくつか説明します。場合によっては、他の API または汎用 API を使用して、アイデアを提示していますが、同じ概念を Google Cloud SQL API にも適用できます。
gzip の使用
各リクエストに必要な帯域幅を削減するための簡単で便利な方法として、gzip 圧縮を有効にする方法があります。この方法では、結果を解凍するために CPU 時間が余分に必要になりますが、ネットワーク費用とのバランスを考えると、時間をかける価値は十分にあります。
gzip でエンコードされたレスポンスを受け取るには、2 つの準備作業が必要です。1 つは、Accept-Encoding
ヘッダーを設定すること、もう 1 つは、ユーザー エージェントに gzip
という文字列を追加することです。以下に、gzip 圧縮を有効にするための正しい形式の HTTP ヘッダーの例を示します。
Accept-Encoding: gzip User-Agent: my program (gzip)
リソースの部分的な使用
API 呼び出しのパフォーマンスを向上させるためのもう 1 つの方法は、データの必要な部分のみを送受信することです。これにより、アプリケーションが不要なフィールドを転送、解析、格納することがなくなるため、ネットワーク、CPU、メモリなどのリソースをより効率的に使用できます。
部分リクエストには次の 2 種類があります。
- 部分レスポンス: レスポンスに含めるフィールドを指定するリクエスト(
fields
リクエスト パラメータを使用)。 - パッチ: 変更するフィールドのみを送信する更新リクエスト(HTTP 動詞
PATCH
を使用)。
以下の各セクションで、部分リクエストの作成方法の詳細について説明します。
部分レスポンス
デフォルトでは、サーバーは、リクエストを処理した後、リソース全体を返します。パフォーマンスを向上させるには、必要なフィールドのみを送信するようサーバーに要求して、部分レスポンスを受信します。
部分レスポンスをリクエストするには、fields
リクエスト パラメータを使って必要なフィールドを指定します。このパラメータは、レスポンス データを返す任意のリクエストに指定できます。
fields
パラメータはレスポンス データにのみ影響を与えます。送信する必要があるデータには影響を与えません。リソースを変更するときに送信するデータ量を削減するには、patch リクエストを使用します。
例
以下の例では、fields
パラメータの使い方を汎用的な(架空の)Demo API を用いて示します。
簡単なリクエスト: 次の HTTP GET
リクエストでは、fields
パラメータを省略しているため、リソース全体が返されます。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY
全リソース レスポンス: 全リソースデータには以下のフィールドが含まれます(他にも多くのフィールドがありますが簡略化するため一部のみ表示してあります)。
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
部分レスポンスのリクエスト: 同じリソースに対する次のリクエストでは、fields
パラメータを指定して、返されるデータ量を大幅に削減しています。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
部分レスポンス: 上記のリクエストに対するレスポンスとして、サーバーは、種類情報、および各アイテムの HTML タイトルと長さのみを含む削減されたアイテム配列が格納されたレスポンスを返します。
200 OK { "kind": "demo", "items": [ { "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ]
レスポンスとして返されるのは、選択したフィールドとそれらのフィールドが属する親オブジェクトのみを含む JSON オブジェクトです。
次のセクションで、fields
パラメータの形式の指定方法について説明し、さらにその後に、レスポンスとして返される具体的な内容について詳細に説明します。
fields パラメータの構文のまとめ
fields
リクエスト パラメータの形式は、XPath の構文に基づいています。サポートされている構文を以下にまとめます。その後のセクションで追加の例を挙げて説明します。
- 複数のフィールドを選択するには、カンマ区切りリストを使用します。
- フィールド
a
内にネストされているフィールドb
を選択するにはa/b
と指定します。b
内にネストされているフィールドc
を選択するにはa/b/c
と指定します。
例外: data ラッパーを使用した API レスポンスの場合、
data: { ... }
のように、data
オブジェクト内にレスポンスがネストされます。この場合、fields
の指定に「data
」を含めないでください。data/a/b
のように、fields 指定内にオブジェクトを含めるとエラーになります。そうした場合は、fields
のように単にa/b
指定を使用してください。 - サブセレクタを使用して特定の配列またはオブジェクトのサブフィールドのセットをリクエストするには、式をかっこ
( )
で囲みます。たとえば、
fields=items(id,author/email)
と指定すると、items 配列内の各要素について、アイテム ID と作者のメールアドレスのみが返されます。サブフィールドは 1 つだけでもかまいません。たとえば、fields=items(id)
と指定するのと、fields=items/id
と指定するのは等価です。 - 必要に応じて、フィールドの選択にワイルドカードを使用します。
たとえば、
fields=items/pagemap/*
と指定すると、ページマップ内のすべてのオブジェクトが選択されます。
fields パラメータのその他の使用例
以下にいくつか例を挙げて、fields
パラメータ値がレスポンスに与える影響を説明します。
注: すべてのクエリ パラメータ値と同様に、fields
パラメータ値も URL エンコードする必要があります。このドキュメントの例では、読みやすさを優先してエンコーディングを省略しています。
- 返して欲しいフィールドを特定する(すなわち、フィールド選択を行う)
fields
リクエスト パラメータ値はフィールドのカンマ区切りリストであり、各フィールドは、レスポンスのルートからの相対位置で指定します。したがって、リスト オペレーションを実行する場合、レスポンスは通常、リソースの配列が格納されたコレクションです。単一のリソースを返すオペレーションを実行する場合、各フィールドは当該リソースからの相対位置で指定します。選択したフィールドが配列(または配列の一部)である場合、サーバーは、配列内のすべての要素について、選択された部分を返します。
以下に、コレクション レベルの例を挙げます。
例 効果 items
items 配列内のすべての要素を返します。各要素内のすべてのフィールドが含まれますが、その他のフィールドは含まれません。 etag,items
etag
フィールド、および items 配列内のすべての要素を返します。items/title
配列内のすべての要素について、 title
フィールドのみを返します。
ネストされたフィールドが返されると、レスポンスには、そのフィールドを含む親オブジェクトが毎回含まれます。親フィールド内のその他の子フィールドは、明示的に選択されていない限り含まれません。context/facets/label
label
配列(この配列自体もfacets
オブジェクト内にネストされている)のすべてのメンバーについて、context
フィールドのみを返します。items/pagemap/*/title
items 配列内の各要素について、 title
のすべての子オブジェクトのpagemap
フィールド(存在する場合)のみを返します。
以下に、リソースレベルの例を挙げます。
例 効果 title
リクエストされたリソースの title
フィールドを返します。author/uri
リクエストされたリソースの uri
オブジェクトのauthor
サブフィールドを返します。links/*/href
href
のすべての子オブジェクトのlinks
フィールドを返します。- 部分選択を使用して個々のフィールドの一部のみをリクエストします。
- デフォルトでは、リクエストに特定のフィールドを指定すると、サーバーは、オブジェクト全体または配列要素全体を返します。こうした場合に、特定のサブフィールドのみを含むレスポンスを指定することもできます。それには、"
( )
" 部分選択構文を使用します。以下に例を示します。例 効果 items(title,author/uri)
items 配列内の各要素について、 title
と作者のuri
の値のみを返します。
部分レスポンスの処理
サーバーは、fields
クエリ パラメータを含む有効なリクエストの処理を終えると、HTTP 200 OK
ステータス コードとリクエストされたデータを返送します。fields
クエリ パラメータにエラーがある場合、またはパラメータが無効な場合、サーバーは、HTTP 400 Bad Request
ステータス コード、およびフィールド選択の問題箇所を示すメッセージ(例: "Invalid field selection a/b"
)を返します。
以下は、前出の導入セクションで挙げた部分レスポンスの例です。このリクエストでは、fields
パラメータを使用して返却するフィールドを指定しています。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
部分レスポンスは、たとえば次のようになります。
200 OK { "kind": "demo", "items": [ { "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ]
注: データのページ分割のためのクエリ パラメータ(maxResults
、nextPageToken
など)をサポートしている API では、それらのパラメータを使用して、各クエリの結果のサイズが大きくなりすぎないようにします。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。
パッチ(部分更新)
リソースを変更する際にも不要なデータの送信を回避することができます。変更する個々のフィールドについてのみ更新したデータを送信するには、HTTP 動詞 PATCH
を使用します。このドキュメントで説明する PATCH 構文は、部分更新の古い実装 GData の PATCH 構文に比べて簡素化されています。
以下に示す簡単な例は、パッチを使用して、小さな更新を行うために送信する必要があるデータを最小化する方法を示しています。
例
以下の例では、簡単なパッチ リクエストを使用して、汎用的な(架空の) Demo API リソースのタイトルのみを更新する方法を示します。このリソースには、コメント、一連の特性、ステータス、およびその他のフィールドがありますが、このリクエストは、唯一の更新対象フィールドである title
フィールドのみを送信します。
PATCH https://www.googleapis.com/demo/v1/324 Authorization: Bearer your_auth_token Content-Type: application/json { "title": "New title" }
レスポンス:
200 OK { "title": "New title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }
サーバーは、200 OK
ステータス コード、および更新されたリソース全体を返します。パッチ リクエストに含まれていたのは title
フィールドだけなので、更新前と異なるのはこのフィールドだけです。
注: 部分レスポンスの fields
パラメータとパッチを組み合わせて使用すると、更新リクエストの効率をさらに高めることができます。パッチ リクエストはリクエストのサイズのみを削減します。部分レスポンスはレスポンスのサイズを削減します。ですから、双方向のデータ送信量を削減するには、パッチ リクエストに fields
パラメータを指定します。
パッチ リクエストの構文
パッチ リクエストの本文には、変更するリソース フィールドのみを含めます。フィールドを指定する際には、そのフィールドが存在する親オブジェクトも含める必要があります。これは、部分レスポンスで親オブジェクトが返されるのと同じです。変更されるデータを送信すると、親オブジェクトが存在する場合は、親オブジェクトのデータとマージされます。
- 追加: フィールドを新しく追加するには、新規のフィールドとその値を指定します。
- 変更: 既存のフィールドの値を変更するには、そのフィールドを指定して、新しい値を設定します。
- 削除: フィールドを削除するには、削除するフィールドを指定し、その値に
null
を設定します。たとえば、"comment": null
のように指定します。オブジェクトにnull
を設定することによって、オブジェクト全体を削除することもできます(オブジェクトが変更可能な場合)。Java API クライアント ライブラリを使用する場合は、代わりにData.NULL_STRING
を使用します。詳しくは、JSON null をご覧ください。
配列に関する注意: 配列を含むパッチ リクエストを実行すると、既存の配列が指定した配列で置換されます。配列内のアイテムを部分的に変更、追加、または削除することはできません。
パッチを読み取り - 変更 - 書き込みサイクルで使用する
変更する必要のあるデータの部分レスポンスを取得することから始めてみると良い練習になります。これは、ETag を使用するリソースでは特に重要になります。というのは、このようなリソースは、If-Match
HTTP ヘッダーに最新の ETag 値を指定しないと、正常に更新できないからです。データを取得したら、変更する必要がある値を変更して、変更した部分をパッチ リクエストで返送します。以下に、Demo リソースで ETag が使用されていると仮定した場合の例を示します。
GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token
部分レスポンスは次のようになります。
200 OK { "etag": "ETagString" "title": "New title" "comment": "First comment.", "characteristics": { "length": "short", "level": "5", "followers": ["Jo", "Will"], } }
以下のパッチ リクエストは、上記のレスポンスを使用しています。以下に示すとおり、このリクエストでは fields
パラメータを使用して、パッチ レスポンスで返されるデータを制限しています。
PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json If-Match: "ETagString" { "etag": "ETagString" "title": "", /* Clear the value of the title by setting it to the empty string. */ "comment": null, /* Delete the comment by replacing its value with null. */ "characteristics": { "length": "short", "level": "10", /* Modify the level value. */ "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */ "accuracy": "high" /* Add a new characteristic. */ }, }
サーバーからは、200 OK HTTP ステータス コードと、リソースの更新された部分が返されます。
200 OK { "etag": "newETagString" "title": "", /* Title is cleared; deleted comment field is missing. */ "characteristics": { "length": "short", "level": "10", /* Value is updated.*/ "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */ "accuracy": "high" /* New characteristic is present. */ } }
パッチ リクエストを直接作成する
一部のパッチ リクエストは、あらかじめ取得しておいたデータに基づいて作成する必要があります。たとえば、配列にアイテムを追加したいが、既存の配列要素はそのまま維持したい場合は、最初に既存のデータを取得する必要があります。同様に、API で ETag が使用されている場合は、リクエストで変更前の ETag 値を送信してからでないと、リソースを正常に更新できません。
注: "If-Match: *"
HTTP ヘッダーを使用すると、ETag が使用されている場合でもパッチ処理を強制的に進めることができます。その場合は、書き込む前に読み取る必要はありません。
上記のようなケースを除けば、事前に既存のデータを取得することなく、パッチ リクエストを直接作成できます。たとえば、フィールドを新しい値に更新するパッチ リクエストや新しいフィールドを追加するパッチ リクエストを簡単にセットアップできます。以下に例を示します。
PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json { "comment": "A new comment", "characteristics": { "volume": "loud", "accuracy": null } }
このリクエストでは、comment フィールドに既存の値が存在する場合は、新しい値で既存の値が上書きされ、そうでない場合は、新しい値が設定されます。同様に、volume 特性が存在する場合は、その値が上書きされ、存在しない場合は作成されます。accuracy フィールドが設定されている場合は、削除されます。
パッチに対するレスポンスを処理する
有効なパッチ リクエストを処理すると、API は、200 OK
HTTP レスポンス コードと、変更済みリソース全体を返します。API で ETag が使用されている場合、サーバーは、パッチ リクエストを正常に処理した時点で ETag 値を更新します。これは、PUT
と同じ動作です。
パッチ リクエストは、fields
パラメータを使用して返却するデータ量を削減しない限り、リソース全体を返します。
パッチ リクエストを実行すると、更新後の新しいリソースが構文的または意味的に無効な状態になる場合、サーバーは、400 Bad Request
や 422 Unprocessable Entity
などの HTTP ステータス コードを返し、リソースの状態はそのままで変更されません。たとえば、必須フィールドの値を削除しようとすると、サーバーはエラーを返します。
PATCH HTTP 動詞がサポートされていない場合の代替表記
ファイアウォールによって HTTP PATCH
リクエストが拒否される場合は、HTTP POST
リクエストを実行して、オーバーライド ヘッダーに PATCH
を設定します。以下に例を示します。
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
パッチと更新の相違点
実際には、HTTP 動詞 PUT
を使用した更新リクエスト用のデータを送信する場合でも、必須フィールドであれ任意指定のフィールドであれ、必要なフィールドを送信するだけで済みます。サーバーによって設定されるフィールドの値を送信すると、その値は無視されます。これは、一見すると、部分更新と同じことをしているように思えますが、このアプローチには制限があります。HTTP 動詞 PUT
を使用した更新では、必須パラメータを省略するとリクエストは失敗し、任意指定のパラメータを省略するとすでに設定済みのデータがクリアされてしまいます。
このため、パッチを使用したほうが安全です。パッチを使用すれば、変更したいフィールドのデータを指定するだけで済みます。省略したフィールドがクリアされることはありません。このルールの唯一の例外は要素または配列の繰り返しです。繰り返される要素または配列をすべて省略すると、何も変更されません。繰り返される要素または配列のいずれかを指定すると、指定した内容で繰り返し全体が置換されます。