このページでは、ローカル データソースからデータを読み込むオペレーションについて説明します。
ローカル データソースからのデータの読み込みに関するチュートリアルについては、以下をご覧ください。
概要
次のいずれかを使用して、読み取り可能なデータソース(ローカルマシンなど)からデータを読み込むことができます。
- Cloud Console
bq
コマンドライン ツールのbq load
コマンド- API
- クライアント ライブラリ
Cloud Console または bq
コマンドライン ツールを使用してデータを読み込むと、読み込みジョブが自動的に作成されます。
制限事項
ワイルドカードやカンマ区切りのリストは、ローカル データソースからファイルを読み込む場合にはサポートされません。ファイルは個別に読み込む必要があります。
必要な権限
データを BigQuery に読み込むには最低限、次の権限が付与されている必要があります。
bigquery.tables.create
。新しいテーブルを作成する場合に必要です。bigquery.tables.updateData
。テーブルを上書きまたは追加する場合に必要です。bigquery.jobs.create
。読み込みジョブを実行する場合に必要です。
次の事前定義済みの IAM ロールには bigquery.tables.create
権限と bigquery.tables.updateData
権限の両方が含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
次の事前定義済みの IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、ユーザーはデータセット内のテーブルにデータを読み込むことができます。
BigQuery での IAM のロールと権限の詳細については、アクセス制御をご覧ください。
データをローカル データソースから読み込む
ローカル データソースから BigQuery にデータを読み込むには、最初にカプセル化データセットが存在している必要があります。データセット作成の詳細については、データセットの作成ページをご覧ください。
データをローカル データソースから読み込むには:
Console
Cloud Console で [BigQuery] ページを開きます。
ナビゲーション パネルの [リソース] セクションで、Google Cloud プロジェクトを展開し、データセットを選択します。
ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [アップロード] を選択します。
[ファイルを選択] の下の [参照] をクリックします。
一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。
ファイル形式として、CSV、JSON(改行区切り)、Avro、Parquet または ORC を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[Schema] セクションでスキーマ定義を入力します。
CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
次の方法でスキーマ情報を手動で入力することもできます。
[テキストとして編集] をクリックし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
[詳細オプション] セクションで該当の項目を選択し、[テーブルを作成] をクリックします。使用可能なオプションについては、CSV のオプションと JSON のオプションをご覧ください。
bq
bq load
コマンドを使用して source_format
を指定し、ローカル ファイルへのパスも指定します。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
デフォルト プロジェクト以外のプロジェクトのデータを読み込む場合は、PROJECT_ID:DATASET
の形式でプロジェクト ID をデータセットに追加します。
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
以下を置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。FORMAT
:CSV
、AVRO
、PARQUET
、ORC
、NEWLINE_DELIMITED_JSON
。project_id
: プロジェクト ID。dataset
: 既存のデータセット。table
: データの読み込み先のテーブル名。path_to_source
: ローカル ファイルへのパス。schema
: 有効なスキーマ。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect
フラグを使用することもできます。
その他にも、BigQuery によるデータの解析方法を制御するオプションに対応するフラグを追加できます。たとえば、--skip_leading_rows
フラグを使用すると、CSV ファイル内のヘッダー行が無視されます。詳細については、CSV のオプションと JSON のオプションをご覧ください。
例:
次のコマンドは、改行区切りの JSON ファイル(mydata.json
)を、ローカルマシンからデフォルト プロジェクトの mydataset
内にある mytable
という名前のテーブルに読み込みます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
次のコマンドは、CSV ファイル(mydata.csv
)をローカルマシンから myotherproject
の mydataset
内にある mytable
という名前のテーブルに読み込みます。スキーマは、FIELD:DATA_TYPE, FIELD:DATA_TYPE
の形式でインラインで定義されます。
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
次のコマンドは、CSV ファイル(mydata.csv
)をローカルマシンからデフォルト プロジェクトの mydataset
内にある mytable
という名前のテーブルに読み込みます。スキーマはスキーマ自動検出を使用して定義されます。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、UploadCsvOptions
の代わりに、JobCreationOptions 基本クラスから適切な形式のアップデート オプション クラスを選択します。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、NewReaderSource
の DataFormat プロパティを適切な形式に設定します。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、FormatOptions を該当の形式に設定します。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、load 関数のmetadata
パラメータを適切な形式に設定します。
PHP
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、sourceFormat を該当の形式に設定します。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、LoadJobConfig.source_format プロパティを適切な形式に設定します。
Ruby
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、Table#load_job メソッドのformat
パラメータを適切な形式に設定します。
ローカル ファイルを使用してテーブルに追加または上書きする
テーブルに追加のデータを読み込むには、ソースファイルから読み込むか、クエリ結果を追加します。データのスキーマが追加先のテーブルまたはパーティションのスキーマと一致しない場合は、追加または上書きするときにスキーマを更新できます。
データの追加時にスキーマを更新する場合、BigQuery では次のことが可能です。
- 新しいフィールドを追加する
- フィールドのモードを
REQUIRED
からNULLABLE
に緩和する
テーブルを上書きする場合、スキーマは必ず上書きされます。テーブルを上書きするとき、スキーマの更新は制限されません。
Cloud Console では、[書き込み設定] オプションを使用して、ソースファイルまたはクエリ結果からデータを読み込むときに行う操作を指定します。bq
コマンドライン ツールと API には、次のオプションがあります。
Console のオプション | bq ツールのフラグ |
BigQuery API のプロパティ | 説明 |
---|---|---|---|
Write if empty | なし | WRITE_EMPTY | テーブルが空の場合にのみデータを書き込みます。 |
テーブルに追加する | --noreplace または --replace=false (--replace を指定しない場合、デフォルトは追加) |
WRITE_APPEND | (デフォルト)テーブルの末尾にデータを追加します。 |
テーブルを上書きする | --replace または --replace=true |
WRITE_TRUNCATE | 新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。 |
CSV、JSON、Avro、Parquet、ORC のデータをローカル ファイルから読み込んで BigQuery テーブルに追加またはテーブルを上書きするには、次の操作を行います。
Console
Cloud Console で [BigQuery] ページを開きます。
ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [アップロード] を選択します。
[ファイルを選択] の下の [参照] をクリックします。
一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。
ファイル形式として、CSV、JSON(改行区切り)、Avro、Parquet または ORC を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[Schema] セクションでスキーマ定義を入力します。
CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
次の方法でスキーマ情報を手動で入力することもできます。
[テキストとして編集] をクリックし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
[詳細オプション] セクションの [書き込み設定] で、[空の場合に書き込む]、[テーブルに追加する]、または [テーブルを上書きする] を選択します。
[テーブルを作成] をクリックします。
bq
テーブルを上書きするには、--replace
フラグを指定して bq load
コマンドを入力します。テーブルにデータを追加するには、--noreplace
フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
テーブルに追加またはテーブルを上書きするときは、--schema_update_option
フラグを使用して、宛先テーブルのスキーマを新しいデータのスキーマに更新できます。--schema_update_option
フラグと一緒に以下のオプションを使用できます。
ALLOW_FIELD_ADDITION
: スキーマに新しいフィールドを追加します。新しいフィールドをREQUIRED
にすることはできません。ALLOW_FIELD_RELAXATION
: Required のフィールドを Nullable に緩和します。値のリストを指定するには、このオプションを繰り返します。
bq --location=LOCATION load \ --[no]replace \ DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
以下を置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。DATASET
: 既存のデータセット。TABLE
: データの読み込み先のテーブル名。PATH_TO_SOURCE
: ローカル ファイルへのパス。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。SCHEMA
: 有効なスキーマ。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect
フラグを使用することもできます。
さらに、データがどのように解析されるかを制御する JSON のオプションまたは CSV のオプションに対応するフラグも追加できます。
例:
次のコマンドは、mydata.json
からデータを読み込んで mydataset
内の mytable
というテーブルを上書きします。スキーマはスキーマ自動検出を使用して定義されます。
bq load \
--autodetect \
--replace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json
次のコマンドは、mydata.json
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。スキーマは、JSON スキーマ ファイル myschema.json
を使用して定義されます。
bq load \
--autodetect \
--noreplace \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
次のコマンドは、mydata.json
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。myschema.json
という名前のローカル JSON スキーマ ファイルが使用されます。スキーマ定義には、宛先テーブルに存在しない新しいフィールドが含まれています。
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
次のコマンドは、mydata.csv
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。myschema.json
という名前のローカル JSON スキーマ ファイルが使用されます。スキーマ定義によって 2 つの REQUIRED
フィールドが NULLABLE
に変更(緩和)されます。
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.csv \
./myschema.json
API アップロード
メディア アップロード機能により、BigQuery API でクラウドにデータを保存し、サーバーで利用できるようになります。写真、動画、PDF ファイル、zip ファイルなど、さまざまな形式のデータをアップロードできます。
アップロード オプション
BigQuery API を使用して、特定の種類のバイナリデータまたはメディアをアップロードできます。アップロードできるデータの性質については、メディア アップロードをサポートするメソッドのリファレンス ページをご覧ください。
- 最大アップロード ファイルサイズ: このメソッドで保存できるデータの最大量。
- 受け入れ可能なメディア MIME タイプ: このメソッドで保存できるバイナリデータの種類。
次のいずれかの方法でアップロードをリクエストできます。使用するメソッドは、uploadType
リクエスト パラメータで指定します。
- マルチパート アップロード:
uploadType=multipart
。比較的小さいファイルとメタデータを高速転送します。ファイルおよびそれを記述するメタデータが、1 つのリクエストですべて転送されます。 - 再開可能なアップロード:
uploadType=resumable
。信頼性の高い転送で、特に、比較的大きいファイルで使用されます。このメソッドでは、セッション開始リクエストを使用します。オプションでメタデータを含めることができます。この方法は小さいファイルでも機能します(アップロードごとに HTTP リクエストが 1 つ追加されます)。したがって、ほとんどのアプリケーションでこれを使用できます。
メディアをアップロードするときは、特別な URI を使用します。具体的には、メディア アップロードをサポートするメソッドには次の 2 種類の URI エンドポイントがあります。
- /upload URI。メディアに使用されます。アップロード エンドポイントの形式は、標準リソース URI に「/upload」接頭辞を付けたものです。この URI は、メディアデータそのものを転送するときに使用します。例:
POST /upload/bigquery/v2/projects/projectId/jobs
- メタデータの場合、標準リソース URI。リソースにデータ フィールドが含まれている場合、これらのフィールドは、アップロードするファイルを記述するメタデータの保管に使用されます。この URI は、メタデータ値の作成または更新の際に使用できます。例:
POST /bigquery/v2/projects/projectId/jobs
マルチパート アップロード
アップロードするデータとともにメタデータを送信する場合は、1 つの multipart/related
リクエストを作成できます。これは、送信するデータが小さく、接続が失敗しても全体を再アップロードできる場合に適しています。
マルチパート アップロードを使用するには、メソッドの /upload URI に対する POST
リクエストを行い、クエリ パラメータ uploadType=multipart
を追加します。次に例を示します。
POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart
マルチパート アップロード リクエストを作成するときに使用する最上位 HTTP ヘッダーには、以下を含めます。
Content-Type
。これを multipart/related に設定し、リクエストの各部分の識別に使用する境界文字列を含めます。Content-Length
。リクエスト本文の合計バイト数を設定します。リクエストのメディア部分は、このメソッドに関して指定された最大ファイルサイズより小さくなければなりません。
リクエスト本文の形式は multipart/related
コンテンツ タイプ [RFC2387] となり、必ず 2 つの部分が含まれます。各部分は境界文字列で区別され、最後の境界文字列には後に 2 つのハイフンが続きます。
マルチパート リクエストの各部分には、次の Content-Type
ヘッダーを追加する必要があります。
- メタデータ部分: 最初に配置する必要があります。
Content-Type
は、受け入れ可能なメタデータ形式のいずれかと一致する必要があります。 - メディア部分: 2 番目に配置する必要があります。
Content-Type
は、メソッドで受け入れ可能なメディア MIME タイプのいずれかと一致する必要があります。
各メソッドで使用できるメディア MIME タイプと、アップロードできるファイルのサイズの上限については、API リファレンスをご覧ください。
注: 関連付けられたデータをアップロードせずに、メタデータ部分のみを生成または更新するには、単に POST
または PUT
リクエストを標準リソース エンドポイント(https://www.googleapis.com/bigquery/v2/projects/projectId/jobs
)に送信します。
例: マルチパート アップロード
次の例は、BigQuery API に対するマルチパート アップロード リクエストを示します。
POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Type: multipart/related; boundary=foo_bar_baz Content-Length: number_of_bytes_in_entire_request_body --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "configuration": { "load": { "sourceFormat": "NEWLINE_DELIMITED_JSON", "schema": { "fields": [ {"name": "f1", "type": "STRING"}, {"name": "f2", "type": "INTEGER"} ] }, "destinationTable": { "projectId": "projectId", "datasetId": "datasetId", "tableId": "tableId" } } } } --foo_bar_baz Content-Type: */* CSV, JSON, AVRO, PARQUET, or ORC data --foo_bar_baz--
リクエストが成功すると、HTTP 200 OK
ステータス コードとメタデータがサーバーから返されます。
HTTP/1.1 200 Content-Type: application/json { "configuration": { "load": { "sourceFormat": "NEWLINE_DELIMITED_JSON", "schema": { "fields": [ {"name": "f1", "type": "STRING"}, {"name": "f2", "type": "INTEGER"} ] }, "destinationTable": { "projectId": "projectId", "datasetId": "datasetId", "tableId": "tableId" } } } }
再開可能なアップロード
より信頼性の高い方法でデータファイルをアップロードするには、再開可能なアップロード プロトコルを使用します。このプロトコルを使用すると、通信障害によってデータのフローが中断しても、その後アップロード オペレーションを再開できます。この方法は特に、大容量のファイルを転送するときや、モバイル クライアント アプリからのアップロードなどでネットワークの中断やその他の送信エラーが起こる可能性が高いときに役立ちます。また、ネットワーク障害が発生した場合に大容量のファイルのアップロードを最初からやり直す必要がなくなり、使用する帯域幅を削減できます。
再開可能なアップロードを使用する手順は、以下のとおりです。
- 再開可能なセッションを開始します。アップロード URI(メタデータがある場合は、メタデータを含むアップロード URI)に対する最初のリクエストを作成します。
- 再開可能なセッション URI を保存します。最初のリクエストのレスポンスで返されるセッション URI を保存します。この URI をこのセッションの他のリクエストで使用します。
- ファイルをアップロードします。再開可能なセッション URI にメディア ファイルを送信します。
また、再開可能なアップロードを使用するアプリには、中断したアップロードを再開するためのコードが必要です。アップロードが中断した場合、正常に受信されたデータの量を判別し、そのポイントからアップロードを再開します。
注: アップロード URI の有効期間は 1 週間です。
手順 1: 再開可能なセッションを開始する
再開可能なアップロードを開始するには、メソッドの /upload URI に対する POST
リクエストを行い、クエリ パラメータ uploadType=resumable
を追加します。次に例を示します。
POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable
この開始リクエストでは本文が空であるか、メタデータのみが含まれています。アップロードするファイルの実際の内容は、後続のリクエストで転送します。
最初のリクエストでは、次の HTTP ヘッダーを使用します。X-Upload-Content-Type
。後続のリクエストで転送するアップロード データのメディア MIME タイプを設定します。X-Upload-Content-Length
。後続のリクエストで転送するアップロード データのバイト数を設定します。このリクエストの時点で長さが不明な場合は、このヘッダーを省略できます。- メタデータを提供する場合:
Content-Type
。メタデータのデータ型に応じて設定します。 Content-Length
。最初のリクエストの本文で提供するバイト数を設定します。チャンク形式転送エンコードを使用する場合は不要です。
各メソッドで使用できるメディア MIME タイプと、アップロードできるファイルのサイズの上限については、API リファレンスをご覧ください。
例: 再開可能なセッション開始リクエスト
次の例は、BigQuery API の再開可能なセッションを開始する方法を示しています。
POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Length: 38 Content-Type: application/json; charset=UTF-8 X-Upload-Content-Type: */* X-Upload-Content-Length: 2000000 { "configuration": { "load": { "sourceFormat": "NEWLINE_DELIMITED_JSON", "schema": { "fields": [ {"name": "f1", "type": "STRING"}, {"name": "f2", "type": "INTEGER"} ] }, "destinationTable": { "projectId": "projectId", "datasetId": "datasetId", "tableId": "tableId" } } } }
注: 最初の再開可能な更新リクエストをメタデータなしで発行する場合は、リクエスト本文を空のままにして、Content-Length
ヘッダーを 0
に設定します。
次に、レスポンスを処理する方法を説明します。
手順 2:再開可能なセッション URI を保存する
セッション開始リクエストが成功すると、API サーバーは HTTP ステータス コード 200 OK
のレスポンスを返します。また、再開可能なセッション URI を指定した Location
ヘッダーも返します。下の例に示されている Location
ヘッダーには、このセッションで使用する一意のアップロード ID を指定した upload_id
クエリ パラメータ部分が含まれています。
例: 再開可能なセッション開始のレスポンス
手順 1 のリクエストに対するレスポンスは次のとおりです。
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
上のレスポンス例に示されている Location
ヘッダーの値は、実際にファイルをアップロードするとき、またはアップロード ステータスを照会するときに HTTP エンドポイントとして使用するセッション URI です。
後続のリクエストで使用できるように、このセッション URI をコピーして保存します。
手順 3: ファイルをアップロードする
ファイルをアップロードするには、前の手順で取得したアップロード URI に PUT
リクエストを送信します。アップロード リクエストの形式は次のとおりです。
PUT session_uri
再開可能なファイル アップロードのリクエストを作成するときに使用する HTTP ヘッダーには、Content-Length
を含めます。このフィールドに、このリクエストでアップロードするバイト数(通常はアップロード ファイルのサイズ)を設定します。
例: 再開可能なファイル アップロード リクエスト
現在の例で、全体で 2,000,000 バイトの CSV、JSON、AVRO、PARQUET または ORC のファイルをアップロードする再開可能なリクエストを以下に示します。
PUT https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1 Content-Length: 2000000 Content-Type: */* bytes 0-1999999
リクエストが成功すると、サーバーは HTTP 201 Created
のレスポンスを、このリソースに関連付けられているメタデータとともに返します。再開可能なセッションの最初のリクエストが PUT
だった場合、既存のリソースを更新したときの成功のレスポンスは 200 OK
となり、このリソースに関連付けられているメタデータが返されます。
アップロード リクエストが中断された場合や、サーバーから HTTP 503 Service Unavailable
などの 5xx
レスポンスが返された場合は、中断されたアップロードを再開するに記載された手順に従ってください。
チャンク形式でファイルをアップロードする
再開可能なアップロードでは、ファイルをチャンクに分割して、各チャンクを順にアップロードする一連のリクエストを送信できます。追加のリクエストに付随してパフォーマンス コストが発生するため、この方法は推奨されず、通常は不要です。ただし、1 つのリクエストで転送するデータの量を減らすために、チャンクの使用が必要になることもあります。Google App Engine リクエストの一部のクラスのように、リクエストごとに固定の時間制限がある場合は、この方法が役立ちます。また、たとえばデフォルトでアップロードの進捗表示をサポートしていない古いブラウザに、アップロードの進捗インジケーターを表示することもできます。
中断されたアップロードを再開する
レスポンスを受信する前にアップロード リクエストが終了した場合や、サーバーから HTTP 503 Service Unavailable
レスポンスが返された場合は、中断されたアップロードを再開する必要があります。方法は次のとおりです。
- ステータスをリクエストする。空の
PUT
リクエストをアップロード URI に発行して、アップロードの現在のステータスを照会します。このリクエストの HTTP ヘッダーには、ファイルの現在の位置が不明であることを示すContent-Range
ヘッダーを含める必要があります。たとえば、ファイルの合計サイズが 2,000,000 の場合、Content-Range
を*/2000000
に設定します。ファイル全体のサイズがわからない場合は、Content-Range
を*/*
に設定します。注: アップロードが中断された場合でなくても、チャンク間のステータスをリクエストできます。これは、たとえば古いブラウザにアップロードの進捗インジケーターを表示する場合に役立ちます。
- アップロードされたバイト数を取得する。ステータス クエリからのレスポンスを処理します。サーバーはレスポンスの
Range
ヘッダーを使用して、その時点までに何バイト受信したかを示します。たとえば、Range
ヘッダーが0-299999
の場合、ファイルの先頭から 300,000 バイトを受信したという意味になります。 - 残りのデータをアップロードする。最後に、リクエストを再開する位置を確認して、残りのデータまたは現在のチャンクを送信します。どちらの場合も、残りのデータを独立したチャンクとして扱う必要があります。つまり、アップロードを再開するときに
Content-Range
ヘッダーを送信する必要があります。
例: 中断されたアップロードを再開する
1)アップロード ステータスをリクエストします。
次のリクエストでは、Content-Range
ヘッダーを使用して、2,000,000 バイトのファイルで現在の位置が不明であることを示しています。
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000
2)レスポンスから、これまでにアップロードされたバイト数を抽出します。
サーバーのレスポンスの Range
ヘッダーは、これまでにファイルの先頭の 43 バイトを受信したことを示しています。Range
ヘッダーの上限値を使用して、再開可能なアップロードを開始する位置を決定します。
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: 0-42
注: アップロードが完了している場合、ステータスのレスポンスが 201 Created
または 200 OK
になることがあります。このような状況は、すべてのバイトがアップロードされた後、クライアントがサーバーからレスポンスを受信する前に接続が切断された場合に発生します。
3)中断された位置からアップロードを再開します。
次のリクエストは、ファイルの 43 番目以降の残りのバイトを送信して、アップロードを再開します。
PUT {session_uri} HTTP/1.1 Content-Length: 1999957 Content-Range: bytes 43-1999999/2000000 bytes 43-1999999
おすすめの方法
メディアをアップロードするときは、エラー処理に関連するいくつかのおすすめの方法を知っておくと便利です。
- 接続の中断や次のような
5xx
エラーが原因で失敗したアップロードは、再開または再試行してください。500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- アップロードの再開または再試行のリクエスト時に
5xx
サーバーエラーが返された場合は、指数バックオフ戦略を使用します。こうしたエラーは、サーバーに負荷がかかりすぎているときに発生することがあります。指数バックオフは、大量のリクエストまたは大量のネットワーク トラフィックが発生しているときに、この種の問題の軽減に役立ちます。 - その他の種類のリクエストでは指数バックオフは使用できませんが、何度か再試行できます。リクエストを再試行するときは、再試行の回数を制限します。たとえば、コードで再試行の回数を 10 回までに制限して、それを超えるとエラーが報告されるようにできます。
- 再開可能なアップロードで
404 Not Found
または410 Gone
エラーが発生した場合には、最初から全体のアップロードをやり直します。
指数バックオフ
指数バックオフは、ネットワーク アプリケーションの標準的なエラー処理方法で、クライアントはリクエスト間の遅延を増加させながら、失敗したリクエストを定期的に再試行します。大量のリクエストまたは大量のネットワーク トラフィックが原因でサーバーがエラーを返した場合、指数バックオフはこのようなエラーの処理に適した方法です。逆に、承認認証情報が無効である、ファイルが見つからないなど、ネットワークのボリュームまたはレスポンス タイムに関係のないエラーの処理には適していません。
指数バックオフを適切に使用すると、帯域幅の使用効率が高くなり、より少ないリクエスト数で正常なレスポンスを受け取ることができ、同時実行環境でのリクエストのスループットが最大化します。
シンプルな指数バックオフを実装するフローは次のとおりです。
- API へのリクエストを作成します。
- リクエストの再試行が必要であることを示す
HTTP 503
レスポンスを受信します。 - 1 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
- リクエストの再試行が必要であることを示す
HTTP 503
レスポンスを受信します。 - 2 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
- リクエストの再試行が必要であることを示す
HTTP 503
レスポンスを受信します。 - 4 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
- リクエストの再試行が必要であることを示す
HTTP 503
レスポンスを受信します。 - 8 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
- リクエストの再試行が必要であることを示す
HTTP 503
レスポンスを受信します。 - 16 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
- フローを停止します。エラーをレポートまたはログに記録します。
上記のフローで、random_number_milliseconds は、1,000 ミリ秒以下の乱数です。この乱数は、ランダムな短い遅延を発生させることで負荷をより均等に分散し、サーバーの暴走を防ぐために必要です。random_number_milliseconds の値は、待機するたびに再定義する必要があります。
注: 待機時間は常に (2 ^ n) + random_number_milliseconds(n は 0 から始まる単調増加整数)です。整数 n は、繰り返し(リクエスト)のたびに 1 ずつ増えます。
このアルゴリズムは、n が 5 になると終了するように設定されています。この上限によって、クライアントが無限に再試行を繰り返すことを防ぎます。総遅延時間が約 32 秒になると、リクエストは「回復不能なエラー」と判断されます。再試行の最大回数を増やすこともできます(特に、長いアップロードを行う場合)。ただし、再試行の遅延時間には合理的な上限を設定してください(たとえば 1 分未満)。