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

JSON API

1. gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセス トークンを生成できます。

2. 必要に応じて、アップロードするオブジェクトに設定するメタデータを含む JSON ファイルを作成します。 たとえば、次の JSON ファイルでは、image/png にアップロードするオブジェクトの contentType メタデータを設定します。

   {
       "contentType": "image/png"
   }

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

   curl -i -X POST --data-binary @METADATA_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-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 ヘッダーとともに除外します。
   • INITIAL_REQUEST_LENGTH は、最初のリクエストの本体のバイト数です（例: 79）。
   • BUCKET_NAME は、オブジェクトをアップロードするバケットの名前です。例: my-bucket
   • OBJECT_NAME は、オブジェクトに付ける URL エンコードの名前です。例: pets%2Fdog.png として URL エンコードされているpets/dog.png。手順 2 でオブジェクト メタデータ ファイルに name を含めた場合、この操作は必要ありません。

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

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

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

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

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

XML API

1. gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセス トークンを生成できます。

2. cURL を使用して、空の本文を含む POST Object リクエストで XML API を呼び出します。

   curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Length: 0" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       -H "x-goog-resumable: start" \
       "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   ここで

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

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

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

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

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

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

   必要に応じて、接頭辞 X-Goog-Meta- を付けて、このリクエストの一部としてオブジェクトのカスタム メタデータを追加できます。

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

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 は、現在のリクエストでアップロードするバイト数です。例: 8388608
   • CHUNK_FIRST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の開始バイトです。
   • CHUNK_LAST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の終了バイトです。
   • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。
   • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

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

   リクエストが成功すると、サーバーは 308 Resume Incomplete で応答します。レスポンスに Range ヘッダーが含まれています。

3. アップロードするデータチャンクごとに上記の手順を繰り返します。各レスポンスの Range ヘッダーに含まれる上限値を使用して、後続のチャンクの開始位置を決定します。リクエストで送信されたすべてのバイトがサーバーで受信されているとは限りません。

   必要に応じて、再開可能なアップロードの最後のリクエストに X-Goog-Meta- で始まるヘッダーを追加して、オブジェクトのカスタム メタデータを追加できます。

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 は、現在のリクエストでアップロードするバイト数です。例: 8388608
   • CHUNK_FIRST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の開始バイトです。
   • CHUNK_LAST_BYTE は、アップロードするチャンクに含まれるオブジェクト全体の終了バイトです。
   • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。
   • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

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

   リクエストが成功すると、サーバーは 308 Resume Incomplete で応答します。レスポンスに Range ヘッダーが含まれています。

3. アップロードするデータチャンクごとに上記の手順を繰り返します。各レスポンスの Range ヘッダーに含まれる上限値を使用して、後続のチャンクの開始位置を決定します。リクエストで送信されたすべてのバイトがサーバーで受信されているとは限りません。

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

JSON API

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

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

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

4. 中断されたリクエストに X-Goog-Meta- という接頭辞を持つヘッダーが含まれている場合は、これらのヘッダーをリクエストに追加してアップロードを再開できます。

5. 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_REMAINING は 19999957 になります。
   • NEXT_BYTE は、手順 2 で保存した値の次の整数です。たとえば、手順 2 の値が 42 の場合、NEXT_BYTE の値は 43 になります。
   • LAST_BYTE は、この PUT リクエストに含まれる終了バイトです。たとえば、合計サイズが 20000000 のオブジェクトのアップロードを完了するには、LAST_BYTE の値は 19999999 となります。
   • 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_REMAINING は 19999957 になります。
   • NEXT_BYTE は、手順 2 で保存した値の次の整数です。たとえば、手順 2 の値が 42 の場合、NEXT_BYTE の値は 43 になります。
   • LAST_BYTE は、この PUT リクエストに含まれる終了バイトです。たとえば、合計サイズが 20000000 のオブジェクトのアップロードを完了するには、LAST_BYTE の値は 19999999 となります。
   • TOTAL_OBJECT_SIZE は、アップロードするオブジェクトの合計サイズです。例: 20000000
   • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

JSON API

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

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

   ここで

   • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

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

XML API

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

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

   ここで

   • SESSION_URI は、再開可能なアップロードを開始したときに Location ヘッダーで返された値です。

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