承認
Google Photos Library API へのすべてのリクエストは、認証済みユーザーによって承認される必要があります。
OAuth 2.0 の承認プロセスの詳細は、作成するアプリケーションの種類によって若干異なります。次の一般的なプロセスは、すべての種類のアプリケーションに適用されます。
- 次の手順で承認プロセスを準備します。
- Google API Console を使用してアプリケーションを登録します。
- Library API を有効にして、クライアント ID やクライアント シークレットなどの OAuth の詳細を取得します。詳細については、スタートガイドをご覧ください。
- ユーザーデータにアクセスするには、アプリケーションが特定のアクセス範囲を Google にリクエストします。
- Google はユーザーに同意画面を表示し、アプリケーションがデータをリクエストすることを承認します。
- ユーザーが承認すると、Google は短期間で期限切れとなるアクセス トークンをアプリケーションに提供します。
- アプリケーションは、そのアクセス トークンをアタッチしてユーザーデータをリクエストします。
- Google がリクエストとトークンが有効であると判断すると、リクエストされたデータが返されます。
アプリケーションに適したスコープを判断するには、認可スコープをご覧ください。
アプリケーションの種類によっては、更新トークンを使用して新しいアクセス トークンを取得するなど、追加の手順が必要になる場合もあります。さまざまな種類のアプリケーションのフローの詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
キャッシュ
データを最新の状態に保つ。
パフォーマンス上の理由でメディア（サムネイル、写真、動画など）を一時的に保存する必要がある場合は、使用ガイドラインに従い、60 分以上保存しないでください。
また、約 60 分後に期限切れになる baseUrls も保存しないでください。
ユーザーのライブラリ内のコンテンツを一意に識別するメディア アイテム ID とアルバム ID は、キャッシュの制限から除外されます。これらの ID は無期限に保存できます（アプリケーションのプライバシー ポリシーが適用されます）。メディア アイテム ID とアルバム ID を使用して、適切なエンドポイントでアクセス可能な URL とデータを再度取得します。詳しくは、メディア アイテムを取得するまたはアルバムの一覧表示をご覧ください。
更新するメディア アイテムが多数ある場合は、そのメディア アイテムを返した検索パラメータを保存し、クエリを再送信してデータを再読み込みする方が効率的です。
SSL アクセス
次の URL を使用するすべての Library API ウェブサービス リクエストで HTTPS が必要です。
https://photoslibrary.googleapis.com/v1/service/output?parameters
HTTP 経由のリクエストは拒否されます。
エラー処理
API から返されたエラーの処理方法については、Cloud APIs のエラーの処理をご覧ください。
失敗したリクエストの再試行
指数バックオフで説明されているように、クライアントは指数バックオフを使用して 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 呼び出しは時間の経過とともに均等に分散されず、異なるデバイス間でも毎分 1 分に同期されます。このように設計が不十分なアプリケーションの場合、毎分の開始時に通常の 60 倍のレベルでトラフィックが急増します。
代わりに、ランダムに選択された時刻に 2 つ目のアラームを設定することをおすすめします。この 2 番目のアラームが発生すると、アプリケーションは必要な API を呼び出し、結果を保存します。毎分 0 秒に表示を更新するために、アプリケーションは API を再度呼び出すのではなく、以前に保存された結果を使用します。このアプローチでは、API 呼び出しは時間の経過とともに均等に分散されます。さらに、ディスプレイが更新されても、API 呼び出しによってレンダリングが遅延することはありません。
毎正時以外でも、ターゲットにしないように注意する必要がある一般的な同期時刻は、毎正時と毎朝の午前 0 時です。