Compute Engine API のベストプラクティス

このドキュメントでは、Compute Engine API を使用する際に推奨されるベストプラクティスについて説明します。このドキュメントの対象は、Compute Engine API をすでに使い慣れているユーザーです。初心者は、前提条件と Compute Engine API の使用について学習してください。

ベストプラクティスに従うことで、時間を節約し、エラーを防ぎ、レートに基づく割り当ての影響を軽減できます。

クライアントライブラリを使用する

Compute Engine API にプログラムでアクセスする方法として、クライアントライブラリの使用をおすすめします。クライアントライブラリでは、一般的なプログラミング言語を使用して API にアクセスできるコードが提供されるため、時間の節約になり、コードのパフォーマンスを向上させることができます。

詳細は、Compute Engine クライアントライブラリとクライアントライブラリのベストプラクティスをご覧ください。

Cloud コンソールを使用して REST リクエストを生成する

リソースを作成するときに、Google Cloud コンソールのリソース作成ページまたは詳細ページを使用して REST リクエストを生成します。生成された REST リクエストを使用すると、時間の節約になり、構文エラーを防止できます。

その方法については、REST リクエストの生成をご覧ください。

オペレーションの完了を待つ

オペレーション（リソースを変更する API リクエスト）が完了することや成功することを前提にしないでください。代わりに、Operation リソースの wait メソッドを使用して、オペレーションが完了したことを確認します。リソースを変更しないリクエスト（GET HTTP 動詞を使用した読み取りリクエストなど）は、API レスポンスでリクエストが成功したかどうかが示されているため、検証する必要がありません。したがって、Compute Engine API は、これらのリクエストに対して Operation リソースを返しません。

API リクエストが正常に開始されると、常に HTTP 200 のステータスコードが返されます。200 はサーバーが API リクエストを正常に受信したことを表しますが、このステータスコードはリクエストされたオペレーションが正常に完了したかどうかを示すものではありません。たとえば、200 を受信しても、オペレーションはまだ完了していないか、失敗している可能性があります。

長時間実行オペレーションの作成、更新、削除をリクエストすると、Operation リソースが返されます。これによって、対象のリクエストのステータスを取得します。Operation リソースの status フィールドが DONE の場合、オペレーションは完了しています。ステータスを確認するには、返された Operation リソースのスコープに一致する wait メソッドを使用します。

ゾーンオペレーションの場合は、zoneOperations.wait を使用します。
リージョンオペレーションの場合は、regionOperations.wait を使用します。
グローバルオペレーションの場合は、globalOperations.wait を使用します。

wait メソッドは、オペレーションが完了したとき、またはリクエストが 2 分間の期限に達したときに返されます。wait メソッドを使用すると、クライアントがレスポンスを待たずにサーバーへ続けてリクエストを発行する短いポーリングが回避されます。Operation リソースに対してショートポーリングで get メソッドを使用する代わりに、再試行ループ内で wait メソッドと指数バックオフを使用してリクエストのステータスを確認すると、レートに基づく割り当てを維持し、レイテンシを短縮できます。

wait メソッドの詳細と使用例については、API レスポンスの処理をご覧ください。

リクエストされたオペレーションのステータスを確認するには、オペレーションステータスの確認をご覧ください。

オペレーションの完了を待つ間、オペレーションの最小保持期間を考慮してください。この期間が経過すると、完了したオペレーションがデータベースから削除される可能性があります。

リストの結果をページ分割する

リストメソッド（*.list メソッド、*.aggregatedList メソッド、またはリストを返すその他のメソッドなど）を使用する場合は、可能なときはいつでも結果をページ分割することで、レスポンス全体を確実に読み取れます。ページ分割を行わないと、maxResults クエリパラメータで定められるとおり、最初の 500 個までの要素しか受信できません。

Google Cloud におけるページ分割の詳細については、リストのページ分割をご覧ください。具体的な詳細と例については、使用する list メソッドのリファレンスドキュメント（instances.list など）をご覧ください。

また、Cloud クライアントライブラリを使用してページ分割を処理することもできます。

クライアントサイドのリストフィルタを使用して割り当てエラーを回避する

*.list メソッドまたは *.aggregatedList メソッドでフィルタを使用すると、リクエストからフィルタされて返されるリソースの数が 1 万を超えた場合、追加の割り当て料金が発生します。詳細については、レートに基づく割り当ての filtered_list_cost_overhead をご覧ください。

プロジェクトがこのレートに基づく割り当てを超えると、理由 rateLimitExceeded で 403 エラーが発生します。このエラーを回避するには、リストリクエストにクライアントサイドのフィルタを適用します。

エラーメッセージではなくエラーコードを信頼する

Google API では、google.rpc.Code によって定義された正規のエラーコードを使用する必要がありますが、エラーメッセージは予告なく変更されることがあります。一般にエラーメッセージは、プログラムではなくデベロッパーが読むように意図されています。

詳細については、API エラーをご確認ください。

レートに基づく割り当てを温存するために、クライアントサイドの再試行を最小限に抑える

rateLimitExceeded エラーを防ぎ、レートに基づく割り当てを最大限に活用するには、プロジェクトのクライアントサイドの再試行の回数を最小限に抑えます。プロジェクトのレートに基づく割り当てを温存するには、次のベストプラクティスが役立ちます。

短い間隔でのポーリングを避けます。
バースト機能を慎重かつ選択的に使用します。
指数バックオフを使用して、常に再試行ループ内で呼び出しを行います。
クライアントサイドのレート制限機能を使用します。
アプリケーションを複数のプロジェクトに分割します。

短い間隔でのポーリングを避ける

クライアントがサーバーからのレスポンスを待たずに継続的にリクエストを送信するといった、短い間隔でのポーリングを行わないようにします。短い間隔でポーリングを行うと、不適切なリクエストの捕捉がより困難になります。こうしたリクエストは有用なデータを返すことがなくても、割り当てには計上されます。

短い間隔でポーリングするのではなく、オペレーションの完了を待つべきです。

バースト機能を慎重かつ選択的に使用する

バースト機能を慎重かつ選択的に使用します。バーストとは、短期間に限り、特定のクライアントに多数の API リクエストの実行を許可する動作を指します。一般には、アプリケーションが通常より多くのトラフィック量を処理する必要があるといった例外的なシナリオに対処するためにバーストが行われます。バースト機能を使用すると、急速にレートに基づく割り当ての上限に達するため、必要な場合に限って利用するようにしてください。

バースト機能を使用する必要がある場合は、可能な限り一括インスタンス API やマネージドインスタンスグループなど、専用の一括処理 API を使用してください。

詳細は、一括処理リクエストをご覧ください。

指数バックオフを使用して常に再試行ループ内で呼び出しを行う

指数バックオフを使用して、タイムアウトやレートに基づく割り当ての上限に達するたびにリクエストの間隔を徐々に長くします。

再試行を頻繁に行うことでアプリケーションが過負荷になったり、レートに基づく割り当てを超過したりしないように、再試行ループには指数バックオフを設定する必要があります。設定しない場合は、同じプロジェクト内のすべてのシステムに悪影響が及ぶ可能性があります。

レートに基づく割り当てに達したために失敗したオペレーションの再試行ループが必要な場合は、指数バックオフ戦略を使用して、割り当てバケットが補充されるまでの再試行の間に十分な時間（通常は 1 分ごと）を確保する必要があります。

また、オペレーションの待機がタイムアウトになった際に再試行ループが必要な場合は、指数バックオフ戦略の最大間隔がオペレーションの最小保持期間を超えないようにする必要があります。そうしない場合は、オペレーションの Not Found エラーが発生する可能性があります。

指数バックオフの実装例については、Identity and Access Management API の指数バックオフアルゴリズムをご覧ください。

クライアントサイドのレート制限機能を使用する

クライアントサイドのレート制限機能を使用します。クライアントサイドのレート制限機能は人為的な制限を設定して、問題になっているクライアントが割り当てのうちの一定量しか使用できないようにし、1 つのクライアントがすべての割り当てを使い果たすことを防ぎます。

アプリケーションを複数のプロジェクトに分割する

アプリケーションを複数のプロジェクトに分割すると、割り当てバケットのリクエスト数を最小化することが容易になります。割り当てはプロジェクトレベルで適用されるため、アプリケーションを分割すれば、各アプリケーションが専用の割り当てバケットを使用できます。

チェックリストの概要

次のチェックリストは、Compute Engine API を使用する際のベストプラクティスをまとめたものです。

次のステップ

Compute Engine API を使用する際にパフォーマンスを向上させる方法を確認する。