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

メディアをアップロード

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

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

以下に、単一のメディアアイテムをアップロードする手順の概要を示します。もし複数のメディアアイテムのアップロード（本番環境アプリケーションではたいてい）アップロードに関するおすすめの方法を確認して、アップロードの効率が向上します。

始める前に

必要な認可スコープ

ユーザーのライブラリやアルバムにメディアアイテムをアップロードするには、 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 日間保持されます。メディアアイテムは常にユーザーのライブラリです。メディアアイテムはアルバムに追加しました自動的に作成します。詳細については、認可スコープをご覧ください。

新しいメディアアイテムを作成するには、 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"
      }
    }
   , ...
  ]
}

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 が含まれている。ゼロ以外のステータスコードは、エラーが発生します。

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();
        // ...
    }
}

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

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

通話中にエラーが発生した場合は、ベストプラクティスを参照し、リクエストを再試行してください。画像を挿入できるように、追加されたのを簡単に記録しておくことをおすすめします。アルバムの正しい位置に配置されます。詳細詳しくは、アルバムを作成する。

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

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

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

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

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

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

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

メディアアイテムの作成

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.

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

メディアをアップロード

始める前に

必要な認可スコープ

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

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

REST

Java

PHP

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

REST

Java

PHP

REST

Java

PHP

REST

Java

PHP

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

REST

Java

PHP

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

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

メディア アイテムの作成

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

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

擬似コード

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

擬似コード

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

メディアアイテムの作成

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