再開可能なアップロードを実行する

コンセプトに移動

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

gsutil とクライアント ライブラリで再開可能なアップロードを使用する方法については、ツールと API で再開可能なアップロードがどのように使用されるかをご覧ください。

前提条件

前提条件は使用するツールによって異なります。

JSON API

JSON API を使用してこのガイドを完了するには、適切な IAM 権限が付与されている必要があります。アップロードするバケットが、作成していないプロジェクト内に存在する場合は、プロジェクト オーナーから必要な権限を含むロールを付与してもらうことが必要な場合があります。

特定のアクションに必要な権限の一覧については、JSON メソッドの IAM 権限をご覧ください。

関連するロールのリストについては、Cloud Storage のロールをご覧ください。または、特定の権限が制限されたカスタムロールを作成することもできます。

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

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

JSON API

  1. OAuth 2.0 Playground から認証アクセス トークンを取得します。固有の OAuth 認証情報を使用するように Playground を構成します。手順については、API 認証をご覧ください。
  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 認証情報を使用するように Playground を構成します。手順については、API 認証をご覧ください。
  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 リクエストで JSON API を呼び出します。

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

    ここで

    • OBJECT_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"

    ここで

    • OBJECT_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 ヘッダーで返された値です。

セッション URI がアクティブな間は、必要に応じて何回でもアップロードを再開できます。セッション URI は 1 週間後に期限切れになります。ファイルが正常にアップロードされると、Cloud Storage は 200 OK または 201 created というステータス コードを返します。

アップロードをキャンセルする

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

JSON API

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

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

    ここで

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

XML API

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

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

    ここで

成功した場合、レスポンスには 204 ステータス コードが含まれます。また、アップロードに対するクエリを試行または再開しようとすると、204 レスポンスが返されます。

次のステップ