このドキュメントでは、Compute Engine API を使用する際に推奨されるベスト プラクティスについて説明します。このドキュメントの対象は、Compute Engine API をすでに使い慣れているユーザーです。初心者は、前提条件と Compute Engine API の使用について学習してください。
ベスト プラクティスに従うことで、時間を節約し、エラーを防ぎ、レートに基づく割り当ての影響を軽減できます。
クライアント ライブラリを使用する
Compute Engine API にプログラムでアクセスする方法として、クライアント ライブラリの使用をおすすめします。クライアント ライブラリでは、一般的なプログラミング言語を使用して API にアクセスできるコードが提供されるため、時間の節約になり、コードのパフォーマンスを向上させることができます。
詳細は、Compute Engine クライアント ライブラリとクライアント ライブラリのベスト プラクティスをご覧ください。
Cloud コンソールを使用して REST リクエストを生成する
リソースを作成するときに、 Cloud de Confiance コンソールのリソース作成ページまたは詳細ページを使用して 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 を使用する際のベスト プラクティスをまとめたものです。
- クライアント ライブラリを使用する
- Cloud コンソールを使用して REST リクエストを生成する
- オペレーションの完了を待つ
- リストの結果をページ分割する
- エラー メッセージではなくエラーコードを信頼する
- レートに基づく割り当てを温存するために、クライアントサイドの再試行を最小限に抑える