メディアをアップロード

メディア アイテムのアップロードは、次の 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 日間保持されます。ユーザーのライブラリにはいつでもメディア アイテムを追加できます。メディア アイテムは アルバム 。詳細については、Authorizations 適用できます。

新しいメディア アイテムを作成するには、 mediaItems.batchCreate newMediaItems のリストを指定します。各 newMediaItem には 1 つのアップロードが含まれます simpleMediaItem 内で指定されたトークンとオプションの説明 表示されなくなります。

説明欄は半角 1,000 文字（全角 500 文字）以内で、 ユーザーが作成する意味のあるテキストです。例: 「公園への旅」または 「ホリデー ディナー」ファイル名、プログラムによる変更、 テキスト、タグ、その他の自動生成テキストが読み取られます。

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

ユーザーのライブラリには、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"
      }
    }
  ]
}

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

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

この通話中にエラーが発生した場合は、 プラクティスを確認し、リクエストを再試行してください。マイページ 正常に追加されたかをトラッキングして、その画像を アルバムの正しい位置に配置されます。詳細情報 詳細については、 アルバムをご覧ください。

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

アップロードに関するおすすめの方法

以下のベスト プラクティスとリソースは、全体的な効率の向上に役立ちます。 アップロードあり:

  • 再試行とエラー処理のベスト プラクティスに従う プラクティス、 次の点に留意してください <ph type="x-smartling-placeholder">
      </ph>
    • 429 エラーは、割り当てを超過した場合に発生することがあります。 または、あまりに速すぎる呼び出し回数に対してレート制限が設けられています。確認事項 直前のユーザーになるまで、同じユーザーの batchCreate を呼び出さない 完了したことを示します。
    • 429 エラーの場合、再試行の前に 30s 以上の遅延が必要です。以下を使用します: 指数バックオフ 戦略について説明します。
    • 500 エラーは、サーバーでエラーが発生したときに発生します。アップロードする際は 原因としては、複数の書き込み呼び出し（ batchCreate など）を追加できます。詳細を確認する batchCreate を並行して呼び出さないでください。
  • 再開可能なアップロードのフローを使用して、以下を行います。 ネットワークの中断時でもより堅牢にアップロードできるため、 部分的に完了したアップロードを再開できるため、帯域幅の使用量を節約できます。これは、クライアントのモバイル デバイスからアップロードする場合や、サイズの大きなファイルをアップロードする場合に重要です。

また、アップロード処理の各ステップについて、以下のヒントを参考にしてください。 バイトのアップロード、メディアの作成 あります。

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

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

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

    • ユーザーごとに、batchCreate を順番に呼び出します（ あります。
    • 複数のユーザーの場合は、ユーザーごとに必ず batchCreate 通話を発信します 実行されます。異なるユーザーに対してのみ、並行して呼び出しを行います。

  • できるだけ多くの NewMediaItems を含める batchCreate への呼び出しのたびに発生し、通話の総数を最小化します。 あります。追加できるアイテムは 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.

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