ベストプラクティス

承認

Google Photos API に対するすべてのリクエストは、認証済みのユーザーによって承認される必要があります。

OAuth 2.0 の認証プロセスの詳細は、開発するアプリケーションの種類によって多少異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。

次の手順を行い、承認プロセスの準備をします。
- Google API Console を使用してアプリケーションを登録します。
- Photos API を有効にして、クライアント ID やクライアントシークレットなどの OAuth の詳細を取得します。詳細については、スタートガイドをご覧ください。
ユーザーデータにアクセスするために、アプリケーションが特定のアクセススコープを Google にリクエストします。
Google はユーザーに同意画面を表示します。ユーザーはこの画面で、アプリケーションが一部のユーザーデータをリクエストできるように承認を求められます。
ユーザーが承認すると、Google は短時間で期限切れとなるアクセストークンをアプリケーションに提供します。
アプリケーションはアクセストークンを付加してユーザーデータをリクエストします。
リクエストとトークンが有効であると判断されると、リクエストしたデータが返されます。

アプリケーションに適したスコープを判断するには、承認スコープをご覧ください。

アプリケーションの種類によっては、更新トークンを使用して新しいアクセストークンを取得するなど、プロセスに追加の手順が含まれる場合があります。さまざまな種類のアプリケーションのフローについて詳しくは、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。

キャッシュ

データを最新の状態に維持しましょう。

パフォーマンス上の理由で一時的にメディア（サムネイル、写真、動画など）を保存する必要がある場合は、使用方法のガイドラインに従い、60 分を超えてキャッシュに保存しないでください。

また、約 60 分経過すると期限が切れる baseUrls も保存しないでください。

ユーザーのライブラリ内のコンテンツを一意に識別するメディアアイテム ID とアルバム ID には、キャッシュの制限は適用されません。これらの ID は無期限に保存できます（アプリケーションのプライバシーポリシーの対象となります）。適切なエンドポイントで、メディアアイテム ID とアルバム ID を使用して、アクセス可能な URL とデータを再度取得します。詳細については、メディアアイテムの取得またはアルバムの取得をご覧ください。

更新するメディアアイテムが多数ある場合は、メディアアイテムを返した検索パラメータを保存し、クエリを再送信してデータを再読み込みするほうが効率的な場合があります。

SSL アクセス

次の URL を使用するすべての Photos API ウェブサービスリクエストで HTTPS を使用する必要があります。

https://photoslibrary.googleapis.com/v1/service/output?parameters

HTTP 経由のリクエストは拒否されます。

エラー処理

API から返されたエラーの処理方法について詳しくは、Cloud API のエラーを処理するをご覧ください。

失敗したリクエストの再試行

指数バックオフで説明されているように、クライアントは 5xx エラーに対して指数バックオフで再試行する必要があります。特に記載がない限り、最小遅延は 1 s です。

429 エラーの場合、クライアントは最小 30s の遅延で再試行できます。それ以外のすべてのエラーでは、再試行を行えない場合があります。リクエストがべき等であることを確認し、エラーメッセージで詳細をご確認ください。

指数バックオフ

まれに、リクエストの処理で問題が発生する場合があります。4XX または 5XX の HTTP レスポンスコードを受信したり、クライアントと Google のサーバー間の TCP 接続が失敗したりする場合があります。多くの場合、リクエストを再試行することをおすすめします。元のリクエストが失敗した場合でも、再試行したリクエストが成功する場合があります。ただし、Google のサーバーに繰り返しリクエストを送信するループ状態にならないことが重要です。このループの動作では、クライアントと Google の間のネットワークに負荷がかかり、多くの部分に問題を引き起こす可能性があります。

より適切な方法は、試行間の遅延を増やしながら再試行することです。通常、遅延は試行ごとに指数関数的に増加します。これは指数バックオフとして知られるアプローチです。

また、アプリケーションの呼び出しチェーンの上位に再試行のコードが存在しないように注意する必要があります。存在すると、短時間に連続してリクエストが繰り返し実行されることにつながります。

Google API の適切な使用

不適切に設計された API クライアントは、インターネットと Google のサーバーの両方に必要以上の負荷をかける可能性があります。このセクションでは、API のクライアントのベストプラクティスについて説明します。以下のベストプラクティスに従うと、アプリケーションによる意図しない API の乱用を防ぐことができます。

同期されたリクエスト

Google API に対して同期されたリクエストを大量に送信すると、Google のインフラストラクチャへの分散型サービス拒否（DDoS）攻撃と見なされて処理される可能性があります。これを回避するには、クライアント間で API リクエストの同期をとらないようにする必要があります。

たとえば、現在のタイムゾーンの時刻を表示するアプリケーションを考えます。このアプリケーションは、表示時刻を更新できるように、クライアントのオペレーティングシステムで毎分 0 秒に起動するアラームを設定するものとします。アプリケーションでは、そのアラームに関連する処理の一部として API 呼び出しを行わないようにしてください。

固定のアラームに応答して API 呼び出しを行うと、時間の経過とともに API 呼び出しが均等に分散されるのではなく、異なるデバイス間でも毎分 0 秒に同期されます。これは適切ではありません。設計が不適切なアプリケーションでこのような処理が行われると、毎分 0 秒に通常の 60 倍のレベルでトラフィックが急増します。

対策の 1 つとして、ランダムに選択した時刻に 2 つ目のアラームを設定する方法が考えられます。この 2 つ目のアラームが起動すると、アプリケーションは必要な API を呼び出し、結果を保存します。毎分 0 秒に表示を更新するために、アプリケーションでは API を再度呼び出すのではなく、前回保存した結果を使用します。この方法では API 呼び出しが均等に分散されます。さらに、表示が更新される際に API 呼び出しでレンダリングが遅延することもありません。

毎分 0 秒以外に、同期された処理を行わないように注意する必要がある一般的な時刻は、毎時の開始時点と一日の開始時点（午前 0 時）です。