メディアをアップロード

メディア アイテムのアップロードは 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 の呼び出し回数を減らします。同じユーザーに対しては、必ず前のリクエストが完了してから後続の呼び出しを行うようにしてください。

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

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 タイプを設定します。

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

  • 単一のユーザーに対して 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.

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