メディアをアップロード

メディア アイテムのアップロードは、次の 2 段階の手順で行います。

  1. アップロード エンドポイントを使用して、メディア ファイルのバイト列を Google サーバーにアップロードします。これにより、アップロードされたバイトを識別するアップロード トークンが返されます。
  2. アップロード トークンを使用して batchCreate 呼び出しを行い、ユーザーの Google フォト アカウントにメディア アイテムを作成します。

以下の手順は、単一のメディア アイテムをアップロードするプロセスの概要を示したものです。複数のメディア アイテムをアップロードする場合（本番環境のアプリケーションでは可能性が高い）は、アップロードに関するベスト プラクティスを確認して、アップロードの効率を高めてください。

始める前に

必要な認可スコープ

ユーザーのライブラリやアルバムにメディア アイテムをアップロードするには、photoslibrary.appendonly スコープが必要です。スコープの詳細については、認可スコープをご覧ください。

アップロード可能なファイル形式とサイズ

アップロードできるファイル形式は、次の表のとおりです。

メディアタイプ 使用できるファイル形式 最大ファイルサイズ
写真 AVIF、BMP、GIF、HEIC、ICO、JPG、PNG、TIFF、WEBP、一部の RAW ファイル。 200 MB
動画 3GP、3G2、ASF、AVI、DIVX、M2T、M2TS、M4V、MKV、MMV、MOD、MOV、MP4、MPG、MTS、TOD、WMV。 20 GB

ステップ 1: バイトのアップロード

アップロード リクエストを使用してバイトを Google にアップロードします。アップロード リクエストが成功すると、未加工のテキスト文字列形式のアップロード トークンが返されます。これらのアップロード トークンを使用して、batchCreate 呼び出しでメディア アイテムを作成します。

REST

POST リクエストのヘッダーに次のフィールドを含めます。

ヘッダー フィールド
Content-type application/octet-stream に設定します。
X-Goog-Upload-Content-Type 推奨。アップロードするバイトの MIME タイプに設定します。一般的な MIME タイプには、image/jpeg、image/png、image/gif などがあります。
X-Goog-Upload-Protocol raw に設定します。

POST リクエストのヘッダーは次のようになります。

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

リクエスト本文に、ファイルのバイナリを含めます。

media-binary-data

この POST リクエストが成功すると、未加工のテキスト文字列形式のアップロード トークンがレスポンスの本文として返されます。メディア アイテムを作成するには、batchCreate 呼び出しでこれらのテキスト文字列を使用します。

upload-token

画像の推奨ファイルサイズは 50 MB 未満です。50 MB を超えるファイルでは、パフォーマンスの問題が発生しやすくなります。

Google Photos Library API は、再開可能なアップロードに対応しています。再開可能なアップロードでは、メディア ファイルを複数のセクションに分割し、一度に 1 セクションずつアップロードできます。

ステップ 2: メディア アイテムを作成する

メディア ファイルのバイト数をアップロードしたら、アップロード トークンを使用して Google フォトでメディア アイテムとして作成できます。アップロード トークンは、作成後 1 日間有効です。ユーザーのライブラリにはいつでもメディア アイテムを追加できます。メディア アイテムは、アプリで作成されたアルバムに追加できます。詳しくは、認可スコープをご覧ください。

新しいメディア アイテムを作成するには、newMediaItems のリストを指定して mediaItems.batchCreate を呼び出します。各 newMediaItem には、simpleMediaItem 内に指定されたアップロード トークンと、ユーザーに表示される説明（省略可）が含まれます。

説明欄は 1,000 文字に制限されており、ユーザーが作成した有意なテキストのみを含める必要があります。たとえば、「公園へのお出かけ」や「ホリデー ディナー」などです。ファイル名、プログラマティック タグ、その他の自動生成テキストなどのメタデータは含めないでください。

最適なパフォーマンスを得るには、1 回の呼び出しに複数のメディア アイテムを含めることで、必要な mediaItems.batchCreate の呼び出し回数を減らします。同じユーザーに対しては、必ず前のリクエストが完了してから後続の呼び出しを行うようにしてください。

説明と対応するアップロード トークンを指定することで、ユーザーのライブラリに 1 つまたは複数のメディア アイテムを作成できます。

REST

POST リクエストのヘッダーは次のようになります。

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

リクエストの本文では、newMediaItems のリストを指定する必要があります。

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

albumId と albumPosition を指定して、アルバムの特定の位置にメディア アイテムを挿入することもできます。

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

アルバム内の位置について詳しくは、エンリッチメントの追加をご覧ください。

アイテム作成のレスポンス

mediaItems.batchCreate 呼び出しは、作成しようとした各メディア アイテムの結果を返します。newMediaItemResults のリストはステータスを示し、リクエストの uploadToken が含まれます。ゼロ以外のステータス コードはエラーを示します。

REST

すべてのメディア アイテムが正常に作成されると、HTTP ステータス 200 OK が返されます。一部のメディア アイテムを作成できなかった場合、リクエストは部分的な成功を示す HTTP ステータス 207 MULTI-STATUS を返します。

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

アイテムが正常に追加されると、mediaItemId、productUrl、mediaMetadata を含む mediaItem が返されます。詳しくは、メディア アイテムへのアクセスをご覧ください。

メディア アイテムが動画の場合、最初に処理が必要です。mediaItem は mediaMetadata 内に status を含み、これは動画ファイルの処理状態を表します。新しくアップロードされたファイルはまず PROCESSING のステータスを返し、その後 READY になって使用できるようになります。詳しくは、メディア アイテムへのアクセスをご覧ください。

この呼び出し中にエラーが発生した場合は、おすすめの方法に沿ってリクエストを再試行してください。追加が成功したことを確認できれば、次のリクエストで画像を正しい位置でアルバムに挿入できます。詳細については、アルバムを作成するをご覧ください。

結果は常にアップロード トークンの送信と同じ順序で返されます。

アップロードに関するベスト プラクティス

アップロードの全体的な効率を高めるために、次のベスト プラクティスとリソースを活用してください。

  • 次の点に注意してください。再試行とエラー処理のベスト プラクティスに従ってください。
    • 429 エラーは、割り当てが使い果たされた場合や、呼び出しが短時間に多すぎるためにレート制限が適用された場合に発生することがあります。前のリクエストが完了するまで、同じユーザーに対して batchCreate を呼び出さないようにしてください。
    • 429 エラーの場合、再試行する前に 30s 秒以上の遅延が必要です。リクエストを再試行する際には、指数バックオフ戦略を使用します。
    • 500 エラーは、サーバーでエラーが発生した場合に発生します。アップロード時にこのエラーが発生するのは、同じユーザーに対して複数の書き込み呼び出し（batchCreate など）を同時に行っていることが原因である可能性が高いです。リクエストの詳細を確認し、batchCreate を並行して呼び出さないでください。
  • 再開可能なアップロードのフローを使用して、ネットワーク中断時のアップロードをより堅牢にし、部分的に完了したアップロードを再開できるようにすることで帯域幅の使用量を削減します。これは、クライアントのモバイル デバイスからアップロードする場合や、サイズの大きなファイルをアップロードする場合に重要です。

また、アップロード プロセスの各ステップ（バイトのアップロードとメディア アイテムの作成）で次のヒントを考慮してください。

バイトをアップロードしています

  • （アップロード トークンを取得するための）バイトのアップロードは並行して実行できます。
  • アップロード呼び出しごとに X-Goog-Upload-Content-Type ヘッダーで常に正しい MIME タイプを設定します。

メディア アイテムを作成する

  • 1 人のユーザーに対して batchCreate と同時に呼び出しを行わないでください。

    • ユーザーごとに、batchCreate を連続して呼び出します。
    • 複数のユーザーの場合は、常にユーザーごとに batchCreate を呼び出します。異なるユーザーの呼び出しのみを並行して行います。

  • batchCreate の呼び出しごとに できるだけ多くの NewMediaItems を含めて、呼び出しの合計数を最小限に抑えます。最大 50 個のアイテムを含めることができます。

  • ユーザーが作成した有意義な説明テキストを設定します。説明フィールドには、ファイル名、プログラマティック タグ、その他の自動生成テキストなどのメタデータを含めないでください。

チュートリアルの例

この例では、疑似コードを使用して、複数のユーザーのメディア アイテムのアップロード手順を説明します。このガイドの目的は、アップロード プロセスの両方のステップ（未加工バイトのアップロードとメディア アイテムの作成）の概要を説明することと、効率的で復元力のあるアップロード統合を構築するためのベスト プラクティスを詳しく説明することです。

ステップ 1: 未加工のバイトをアップロードする

まず、すべてのユーザーのメディア アイテムの未加工のバイトをアップロードするキューを作成します。ユーザーごとに返された uploadToken をそれぞれ追跡します。以下のポイントに注意してください。

  • 同時アップロード スレッドの数は、運用環境によって異なります。
  • 必要に応じて、アップロード キューの順序を変更することを検討してください。たとえば、ユーザーごとの残りのアップロード数、ユーザーの全体的な進行状況、その他の要件に基づいてアップロードの優先順位を設定できます。

擬似コード

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

ステップ 2: メディア アイテムを作成する

ステップ 1 では、複数のユーザーから複数のバイトを並行してアップロードできますが、ステップ 2 では、ユーザーごとに一度に 1 つの呼び出ししか行えません。

擬似コード

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

すべてのアップロードとメディア作成呼び出しが完了するまで、このプロセスを続けます。