このページは Cloud Translation API によって翻訳されました。

メディアをアップロードする

メディアアイテムのアップロードは、次の 2 段階のプロセスで行われます。

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

ここでは、1 つのメディアアイテムをアップロードする手順について説明します。複数のメディアアイテムをアップロードする場合（あらゆる製品版アプリケーションでこれに当てはまります）は、アップロードに関するベストプラクティスを確認して、アップロードの効率を高めてください。

始める前に

必要な認可スコープ

ユーザーのライブラリまたはアルバムにメディアアイテムをアップロードするには、photoslibrary.appendonly スコープまたは photoslibrary スコープが必要です。

メディアアイテムは、photoslibrary.sharing スコープを使用して作成することもできます。photoslibrary.sharing スコープを持つアイテムを作成するには、まず shareAlbum を使用してアルバムを作成し、共有としてマークする必要があります。その後、アルバム内でユーザーと共有するメディアアイテムを作成できます。アプリが共有していないアイテムをユーザーのライブラリやアルバムに直接作成することはできません。

アルバムを一覧表示する場合、isWriteable プロパティは、アプリが特定のアルバムにメディアを作成できるかどうかを示します。

使用可能なファイル形式とサイズ

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

メディアタイプ	使用できるファイル形式	最大ファイルサイズ
写真	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

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

画像の推奨ファイルサイズは 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"
      }
    }
   , ...
  ]
}

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

アルバム id を指定すると、ライブラリとアルバムにメディアアイテムを追加できます。詳しくは、アルバムを作成するをご覧ください。

各アルバムには最大 20,000 個のメディアアイテムを含めることができます。この上限を超えるメディアアイテムをアルバム内に作成するリクエストは失敗します。

REST

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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"
  }
}

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

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

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

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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

アイテムが正常に追加されると、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 の呼び出しをユーザーごとに 1 つずつ実行します。複数のユーザーの呼び出しを並行して行ってください。
batchCreate の呼び出しごとにできるだけ多くの NewMediaItems を指定して、必要な呼び出しの総数を最小限に抑えます。追加できるアイテムは 50 個までです。
ユーザーが作成したわかりやすい説明テキストを設定します。説明フィールドには、ファイル名、プログラムによるタグ、その他の自動生成されたテキストなどのメタデータを含めないでください。

サンプルのチュートリアル

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

ステップ 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.

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

メディアをアップロードする

始める前に

必要な認可スコープ

使用可能なファイル形式とサイズ

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

REST

Java

PHP

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

REST

Java

PHP

REST

Java

PHP

REST

Java

PHP

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

REST

Java

PHP

アップロードのベスト プラクティス

バイトのアップロード

メディア アイテムの作成

サンプルのチュートリアル

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

擬似コード

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

擬似コード

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

アップロードのベストプラクティス

メディアアイテムの作成

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