再開可能なアップロードの実行

コンセプトに移動

このページでは、Cloud Storage JSON と XML API で再開可能なアップロード リクエストを行う方法について説明します。このプロトコルを使用すると、通信障害でデータフローが中断した後にアップロード操作を再開できます。

再開可能なアップロードのセッションを開始する

再開可能なアップロードのセッションを開始するには:

JSON API

  1. OAuth 2.0 Playground から承認アクセス トークンを取得します。固有の OAuth 認証情報を使用するようにプレイグラウンドを構成します。
  2. 必要に応じて、アップロードするオブジェクトに設定するメタデータを含む .json ファイルを作成します。

  3. cURL を使用して、POST Object リクエストで JSON API を呼び出します。

    curl -i -X POST --data-binary @METADATA_LOCATION \
        -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Type: application/json" \
        -H "Content-Length: INITIAL_REQUEST_LENGTH" \
        "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

    ここで

    • METADATA_LOCATION は、前の手順で指定したオプションのメタデータを含む JSON ファイルのローカルパスです。メタデータ ファイルを含めない場合は、--data-binary @ および Content-Type ヘッダーとともに除外します。
    • OAUTH2_TOKEN は、手順 1 で生成したアクセス トークンです。
    • INITIAL_REQUEST_LENGTH は、最初のリクエストの本体のバイト数です(例: 79)。チャンク形式転送エンコードを使用する場合は不要です。
    • BUCKET_NAME は、オブジェクトをアップロードするバケットの名前です。例: my-bucket
    • OBJECT_NAME は、オブジェクトに付ける名前です。例: pets/dog.pngステップ 2 のオブジェクト メタデータ ファイルに name を含めた場合、この操作は必要ありません。

    クロスオリジン リソース シェアリングを有効にしている場合、このリクエストと後続のアップロード リクエストに Origin ヘッダーも含める必要があります。

    リクエストに追加できるオプションのヘッダーには、X-Upload-Content-TypeX-Upload-Content-Length があります。

    成功した場合、レスポンスには 200 ステータス コードが含まれます。

  4. レスポンスの Location ヘッダーで指定された再開可能なセッション URIPOST Object リクエストに保存します。

    この URI は、それ以降にオブジェクト データをアップロードするためのリクエストで使用されます。

XML API

  1. OAuth 2.0 Playground から承認アクセス トークンを取得します。固有の OAuth 認証情報を使用するようにプレイグラウンドを構成します。
  2. cURL を使用して、空の本文を含む POST Object リクエストで XML API を呼び出します。

    curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Length: 0" \
        -H "Content-Type: OBJECT_CONTENT_TYPE" \
        -H "x-goog-resumable: start" \
        "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    ここで

    • OAUTH2_TOKEN は、手順 1 で生成したアクセス トークンです。
    • OBJECT_CONTENT_TYPE は、オブジェクトのコンテンツ タイプです。例: image/pngコンテンツ タイプを指定しない場合、Cloud Storage システムはオブジェクトの Content-Type メタデータを application/octet-stream に設定します。
    • BUCKET_NAME は、オブジェクトをアップロードするバケットの名前です。例: my-bucket
    • OBJECT_NAME は、オブジェクトに付ける名前です。例: pets/dog.png

    クロスオリジン リソース シェアリングを有効にしている場合、このリクエストと後続のアップロード リクエストに Origin ヘッダーも含める必要があります。

    成功した場合、レスポンスには 201 ステータス メッセージが含まれます。

  3. レスポンスの Location ヘッダーで指定された再開可能なセッション URIPOST Object リクエストに保存します。

    この URI は、それ以降にオブジェクト データをアップロードするためのリクエストで使用されます。

ファイルをアップロードする

再開可能なアップロードを開始したら、次の 2 つの方法でオブジェクトのデータをアップロードできます。

  • 単一リクエスト。通常はこの方法が最適です。リクエストの数が少なく、パフォーマンスが向上します。
  • 複数のチャンク: 1 つのリクエストで転送されるデータ量を削減する必要がある場合(個々のリクエストに固定された時間制限がある場合など)やアップロードの開始時に合計サイズがわからない場合は、この方法を使用します。

単一のリクエストのアップロード

ファイルを単一リクエストでアップロードするには:

JSON API

  1. cURL を使用して、PUT Object リクエストで JSON API を呼び出します。

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • OBJECT_LOCATION は、オブジェクトへのローカルパスです。例: Desktop/dog.png
    • OBJECT_SIZE は、オブジェクトのバイト数です。例: 20000000
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

XML API

  1. cURL を使用して、PUT Object リクエストで XML API を呼び出します。

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • OBJECT_LOCATION は、オブジェクトへのローカルパスです。例: Desktop/dog.png
    • OBJECT_SIZE は、オブジェクトのバイト数です。例: 20000000
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

アップロードが完了すると、リソースに関連するメタデータとともに 200 OK または 201 Created レスポンスが返されます。

アップロード リクエストが中断するか、5xx レスポンスを受信したら、中断されたアップロードの再開の手順に従います。

複数のチャンク アップロード

複数のチャンクでファイルをアップロードするには:

JSON API

  1. アップロードするファイルからデータのチャンクを作成します。

    チャンクサイズは、256 KiB(256 x 1,024 バイト)の倍数にする必要があります。通常、チャンクサイズが大きいと、アップロードがより効率的になります。チャンクサイズには 8 MiB を使用することをおすすめします。

  2. cURL を使用して、PUT Object リクエストで JSON API を呼び出します。

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • CHUNK_LOCATION は、現在アップロードしているチャンクへのローカルパスです。
    • CHUNK_SIZE は、現在のリクエストでアップロードするバイト数です。例: 524288
    • CHUNK_FIRST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の開始バイトです。
    • CHUNK_LAST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の終了バイトです。
    • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

    Content-Range の例としては、Content-Range: bytes 0-524287/2000000 が考えられます。このヘッダーの詳細については、Content-Range をご覧ください。

    リクエストが成功すると、サーバーは 308 Resume Incomplete で応答します。レスポンスに Range ヘッダーが含まれています。このヘッダーの上限値に基づいて、次のチャンクの始点を決定します。リクエストで送信されたすべてのバイトがサーバーで受信されているとは限りません。

  3. アップロードするデータの残りのチャンクに対して、上記の手順を繰り返します。

XML API

  1. アップロードするファイルからデータのチャンクを作成します。

    チャンクサイズは、256 KiB(256 x 1,024 バイト)の倍数にする必要があります。通常、チャンクサイズが大きいと、アップロードがより効率的になります。チャンクサイズには 8 MiB を使用することをおすすめします。

  2. cURL を使用して、PUT Object リクエストで XML API を呼び出します。

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • CHUNK_LOCATION は、現在アップロードしているチャンクへのローカルパスです。
    • CHUNK_SIZE は、現在のリクエストでアップロードするバイト数です。例: 524288
    • CHUNK_FIRST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の開始バイトです。
    • CHUNK_LAST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の終了バイトです。
    • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

    Content-Range の例としては、Content-Range: bytes 0-524287/2000000 が考えられます。このヘッダーの詳細については、Content-Range をご覧ください。

    リクエストが成功すると、サーバーは 308 Resume Incomplete で応答します。レスポンスに Range ヘッダーが含まれています。このヘッダーの上限値に基づいて、次のチャンクの始点を決定します。リクエストで送信されたすべてのバイトがサーバーで受信されているとは限りません。

  3. アップロードするデータの残りのチャンクに対して、上記の手順を繰り返します。

アップロードが完了すると、リソースに関連するメタデータとともに 200 OK または 201 Created レスポンスが返されます。

チャンク アップロードが中断された場合、または 5xx のレスポンスを受け取った場合は、中断されたアップロードを再開するの手順に沿って対応してください。

再開可能なアップロードのステータスの確認

再開可能なアップロードが中断された場合や、アップロードが完了しているかどうかわからない場合は、アップロードのステータスを確認できます。

JSON API

  1. cURL を使用して、PUT Object リクエストで XML API を呼び出します。

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • OBEJCT_SIZE は、オブジェクトに含まれる合計バイト数です。オブジェクトのフルサイズがわからない場合は、この値に * を使用します。
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

XML API

  1. cURL を使用して、PUT Object リクエストで XML API を呼び出します。

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • OBEJCT_SIZE は、オブジェクトに含まれる合計バイト数です。オブジェクトのフルサイズがわからない場合は、この値に * を使用します。
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

200 OK または 201 Created が返された場合、アップロードは完了しています。これ以上の操作は必要ありません。

308 Resume Incomplete が返された場合、ファイルのアップロードを続行する必要があります。

  • Cloud Storage がまだバイトを受信していない場合、308 レスポンスに Range ヘッダーがありません。この場合、アップロードを最初から開始する必要があります。
  • それ以外の場合、308 レスポンスには、Cloud Storage がこれまでに受信したバイト数を指定する Range ヘッダーが含まれます。中断されたアップロードを再開する場合は、この値を使用します。

中断されたアップロードの再開

レスポンスを受信する前にアップロード リクエストが終了した場合や、503 または 500 レスポンスを受け取った場合は、中断位置から中断されたアップロードを再開します。中断されたアップロードを再開するには以下の処理を行います。

JSON API

  1. 再開可能なアップロードのステータスを確認します。

  2. ステータス チェックに対するレスポンスに含まれる Range ヘッダーの上限値を保存します。レスポンスに Range ヘッダーがない場合、Cloud Storage はまだバイトを受信していないため、最初からアップロードする必要があります。

  3. アップロードしようとしているオブジェクト データが Range ヘッダーの上限値より大きいバイトから始まることを確認します。

  4. cURL を使用して、Range ヘッダーの値の後のバイトを取得する PUT Object リクエストで JSON API を呼び出します。

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • PARTIAL_OBJECT_LOCATION は、アップロードするデータの残りの部分へのローカルパスです。
    • UPLOAD_SIZE_REMAINING は、現在のリクエストでアップロードするバイト数です。たとえば、0~42 バイトのアップロードが完了した後に、合計サイズが 20,000,000 の残りのオブジェクトをアップロードすると、UPLOAD_SIZE_REMAINING1999957 になります。
    • NEXT_BYTE は、手順 2 で保存した値の次の整数です。たとえば、手順 2 の値が 42 の場合、NEXT_BYTE の値は 43 になります。
    • LAST_BYTE は、この PUT リクエストに含まれる終了バイトです。たとえば、合計サイズが 20000000 のオブジェクトのアップロードを完了するには、LAST_BYTE の値は 1999999 となります。
    • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。例: 20000000
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

XML API

  1. 再開可能なアップロードのステータスを確認します。

  2. ステータス チェックに対するレスポンスに含まれる Range ヘッダーの上限値を保存します。レスポンスに Range ヘッダーがない場合、Cloud Storage はまだバイトを受信していないため、最初からアップロードする必要があります。

  3. アップロードしようとしているオブジェクト データが Range ヘッダーの上限値より大きいバイトから始まることを確認します。

  4. cURL を使用して、Range ヘッダーの値の後のバイトを取得する PUT オブジェクト リクエストで XML API を呼び出します。

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    ここで

    • PARTIAL_OBJECT_LOCATION は、アップロードするデータの残りの部分へのローカルパスです。
    • UPLOAD_SIZE_REMAINING は、現在のリクエストでアップロードするバイト数です。たとえば、0~42 バイトのアップロードが完了した後に、合計サイズが 20,000,000 の残りのオブジェクトをアップロードすると、UPLOAD_SIZE_REMAINING1999957 になります。
    • NEXT_BYTE は、手順 2 で保存した値の次の整数です。たとえば、手順 2 の値が 42 の場合、NEXT_BYTE の値は 43 になります。
    • LAST_BYTE は、この PUT リクエストに含まれる終了バイトです。たとえば、合計サイズが 20000000 のオブジェクトのアップロードを完了するには、LAST_BYTE の値は 1999999 となります。
    • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。例: 20000000
    • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

アップロードは必要に応じて何度でも再開できますが、リクエストを再試行するときは、再開可能なアップロードの再試行のガイドラインに沿って操作してください。

ファイルが正常にアップロードされると、Cloud Storage は 200 OK または 201 created というステータス コードを返します。

アップロードのキャンセル

再開可能なアップロードをキャンセルして、それ以上の操作を防ぐには次の処理を行います。

JSON API

  1. cURL を使用して、DELETE リクエストで JSON API を呼び出します。

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    ここで

XML API

  1. cURL を使用して、DELETE リクエストで XML API を呼び出します。

    curl -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    ここで

成功すると、レスポンスに 499 ステータス コードが含まれます。今後、アップロードのクエリまたは再開を試行すると、4xx レスポンスが返されます。

次のステップ