データをローカル データソースから読み込む

このページでは、ローカル データソースからデータを読み込むオペレーションについて説明します。

ローカル データソースからのデータの読み込みに関するチュートリアルについては、以下をご覧ください。

• クイックスタート: Cloud Console の使用
• クイックスタート: bq コマンドライン ツールの使用

概要

次のいずれかを使用して、読み取り可能なデータソース（ローカルマシンなど）からデータを読み込むことができます。

• 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

1. Cloud Console で [BigQuery] ページを開きます。

   [BigQuery] ページに移動

2. ナビゲーション パネルの [リソース] セクションで、Google Cloud プロジェクトを展開し、データセットを選択します。

3. ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

   

4. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

   • [テーブルの作成元] で [アップロード] を選択します。

     

   • [ファイルを選択] の下の [参照] をクリックします。

     

   • 一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。

   • ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。

5. [テーブルを作成] ページの [送信先] セクションで、次の操作を行います。

   • [データセット名] で、該当するデータセットを選択します。

     

   • [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。

   • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

6. [Schema] セクションでスキーマ定義を入力します。

   • CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。

   • 次の方法でスキーマ情報を手動で入力することもできます。

     • [テキストとして編集] をクリックし、テーブル スキーマを JSON 配列として入力します。

       注: 既存のテーブルのスキーマを JSON 形式で表示するには、コマンド bq show --format=prettyjson dataset.table を入力します。

     • [フィールドを追加] を使用して、スキーマを手動で入力します。

7. [詳細オプション] セクションで該当の項目を選択し、[テーブルを作成] をクリックします。使用可能なオプションについては、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

注: コマンドラインでスキーマを指定する場合は、RECORD（STRUCT）型とフィールド記述を含めることはできず、フィールド モードも指定できません。すべてのモードはデフォルトの NULLABLE になります。フィールドの説明、モード、RECORD 型を含めるには、代わりに JSON スキーマ ファイルを指定します。

次のコマンドは、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 基本クラスから適切な形式のアップデート オプション クラスを選択します。

GitHub で表示 フィードバック

using Google.Cloud.BigQuery.V2;
using System;
using System.IO;

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job.PollUntilCompleted();  // Waits for the job to complete.
            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

Go

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、NewReaderSource の DataFormat プロパティを適切な形式に設定します。

GitHub で表示 フィードバック

import (
	"context"
	"fmt"
	"os"

	"cloud.google.com/go/bigquery"
)

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

Java

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、FormatOptions を該当の形式に設定します。

GitHub で表示 フィードバック

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、load 関数の metadata パラメータを適切な形式に設定します。

GitHub で表示 フィードバック

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function loadLocalFile() {
  // Imports a local file into a table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const filename = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、sourceFormat を該当の形式に設定します。

GitHub で表示 フィードバック

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';
// $tableId    = 'The BigQuery table ID';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、LoadJobConfig.source_format プロパティを適切な形式に設定します。

GitHub で表示 フィードバック

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

Ruby

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、Table#load_job メソッドの format パラメータを適切な形式に設定します。

GitHub で表示 フィードバック

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows into #{table.id}"
end

ローカル ファイルを使用してテーブルに追加または上書きする

テーブルに追加のデータを読み込むには、ソースファイルから読み込むか、クエリ結果を追加します。データのスキーマが追加先のテーブルまたはパーティションのスキーマと一致しない場合は、追加または上書きするときにスキーマを更新できます。

データの追加時にスキーマを更新する場合、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

1. Cloud Console で [BigQuery] ページを開きます。

   [BigQuery] ページに移動

2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。

3. ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

   

4. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

   • [テーブルの作成元] で [アップロード] を選択します。

     

   • [ファイルを選択] の下の [参照] をクリックします。

     

   • 一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。

   • ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。

5. [テーブルを作成] ページの [送信先] セクションで、次の操作を行います。

   • [データセット名] で、該当するデータセットを選択します。

     

   • [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。

   • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

6. [Schema] セクションでスキーマ定義を入力します。

   • CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。

   • 次の方法でスキーマ情報を手動で入力することもできます。

     • [テキストとして編集] をクリックし、テーブル スキーマを JSON 配列として入力します。

       注: 既存のテーブルのスキーマを JSON 形式で表示するには、コマンド bq show --format=prettyjson dataset.table を入力します。

     • [フィールドを追加] を使用して、スキーマを手動で入力します。

7. [詳細オプション] セクションの [書き込み設定] で、[空の場合に書き込む]、[テーブルに追加する]、または [テーブルを上書きする] を選択します。

8. [テーブルを作成] をクリックします。

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 ヘッダーを追加する必要があります。

1. メタデータ部分: 最初に配置する必要があります。Content-Type は、受け入れ可能なメタデータ形式のいずれかと一致する必要があります。
2. メディア部分: 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"
      }
    }
  }
}

再開可能なアップロード

より信頼性の高い方法でデータファイルをアップロードするには、再開可能なアップロード プロトコルを使用します。このプロトコルを使用すると、通信障害によってデータのフローが中断しても、その後アップロード オペレーションを再開できます。この方法は特に、大容量のファイルを転送するときや、モバイル クライアント アプリからのアップロードなどでネットワークの中断やその他の送信エラーが起こる可能性が高いときに役立ちます。また、ネットワーク障害が発生した場合に大容量のファイルのアップロードを最初からやり直す必要がなくなり、使用する帯域幅を削減できます。

再開可能なアップロードを使用する手順は、以下のとおりです。

1. 再開可能なセッションを開始します。アップロード URI（メタデータがある場合は、メタデータを含むアップロード URI）に対する最初のリクエストを作成します。
2. 再開可能なセッション URI を保存します。最初のリクエストのレスポンスで返されるセッション URI を保存します。この URI をこのセッションの他のリクエストで使用します。
3. ファイルをアップロードします。再開可能なセッション 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 リクエストの一部のクラスのように、リクエストごとに固定の時間制限がある場合は、この方法が役立ちます。また、たとえばデフォルトでアップロードの進捗表示をサポートしていない古いブラウザに、アップロードの進捗インジケーターを表示することもできます。

展開して詳細を表示

データをチャンク形式でアップロードする場合は、ファイル全体のアップロードに必要な Content-Length ヘッダーに加えて、Content-Range ヘッダーも必要です。

• Content-Length。チャンクサイズを設定します。最後のリクエストでは、チャンクサイズより小さい値になることがあります。
• Content-Range: ファイルの何バイト目から何バイト目までをアップロードするかを設定します。たとえば、Content-Range: bytes 0-524287/2000000 は、2,000,000 バイトのファイルで先頭の 524,288 バイト（256 x 1,024 x 2）をアップロードすることを意味します。

チャンクサイズの制限: 最後にアップロードするチャンクを除き、チャンクのサイズはすべて、256 KB（256 x 1,024 バイト）の倍数にする必要があります。チャンクを使用する場合は、効率的にアップロードするために、チャンクサイズをできるだけ大きくすることが重要です。

例: 再開可能なチャンク形式のファイル アップロード リクエスト

先頭の 524,288 バイトを送信するリクエストは次のようになります。

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: */*
Content-Range: bytes 0-524287/2000000

bytes 0-524288

リクエストが成功すると、サーバーは 308 Resume Incomplete のレスポンスとともに、その時点までに格納された合計バイト数を示す Range ヘッダーを返します。

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

Range ヘッダーで返された上限値を使用して、次のチャンクの開始位置を決定します。ファイル全体のアップロードが完了するまで、ファイルの各チャンクの PUT を続行します。

チャンクの PUT リクエストが中断された場合や、サーバーから HTTP 503 Service Unavailable などの 5xx レスポンスが返された場合は、中断されたアップロードを再開するに記載された手順に従ってください。ただし、ファイルの残りをアップロードするのではなく、中断した位置からチャンクのアップロードを続行します。

注意事項

• 次のチャンクの開始位置を決定するために、必ずレスポンスの Range ヘッダーを使用してください。前のリクエストで送信したすべてのバイトをサーバーがすでに受信したとは限りません。
• アップロード URI にはそれぞれ有効期限があり、いつかは期限切れになります（使用しない場合は約 1 日です）。そのため、アップロード URI を取得したらすぐに再開可能なアップロードを開始し、中断が発生したらすぐにそのアップロードを再開することをおすすめします。
• 有効期限が切れたアップロード セッション ID を使用してリクエストを送信すると、サーバーからステータス コード 404 Not Found が返されます。アップロード セッションで回復不能なエラーが発生すると、サーバーからステータス コード 410 Gone が返されます。この場合は、再開可能なアップロードを新たに開始して新しいアップロード URI を取得し、新しいエンドポイントを使用してアップロードを最初からやり直す必要があります。

ファイル全体のアップロードが完了すると、サーバーは HTTP 201 Created のレスポンスとともに、このリソースに関連付けられているメタデータを返します。このリクエストが新しいエンティティの作成ではなく既存のエンティティの更新リクエストであった場合、完了したアップロードの HTTP レスポンス コードは 200 OK になります。

---

中断されたアップロードを再開する

レスポンスを受信する前にアップロード リクエストが終了した場合や、サーバーから HTTP 503 Service Unavailable レスポンスが返された場合は、中断されたアップロードを再開する必要があります。方法は次のとおりです。

1. ステータスをリクエストする。空の PUT リクエストをアップロード URI に発行して、アップロードの現在のステータスを照会します。このリクエストの HTTP ヘッダーには、ファイルの現在の位置が不明であることを示す Content-Range ヘッダーを含める必要があります。たとえば、ファイルの合計サイズが 2,000,000 の場合、Content-Range を */2000000 に設定します。ファイル全体のサイズがわからない場合は、Content-Range を */* に設定します。

   注: アップロードが中断された場合でなくても、チャンク間のステータスをリクエストできます。これは、たとえば古いブラウザにアップロードの進捗インジケーターを表示する場合に役立ちます。

2. アップロードされたバイト数を取得する。ステータス クエリからのレスポンスを処理します。サーバーはレスポンスの Range ヘッダーを使用して、その時点までに何バイト受信したかを示します。たとえば、Range ヘッダーが 0-299999 の場合、ファイルの先頭から 300,000 バイトを受信したという意味になります。
3. 残りのデータをアップロードする。最後に、リクエストを再開する位置を確認して、残りのデータまたは現在のチャンクを送信します。どちらの場合も、残りのデータを独立したチャンクとして扱う必要があります。つまり、アップロードを再開するときに 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 エラーが発生した場合には、最初から全体のアップロードをやり直します。

指数バックオフ

指数バックオフは、ネットワーク アプリケーションの標準的なエラー処理方法で、クライアントはリクエスト間の遅延を増加させながら、失敗したリクエストを定期的に再試行します。大量のリクエストまたは大量のネットワーク トラフィックが原因でサーバーがエラーを返した場合、指数バックオフはこのようなエラーの処理に適した方法です。逆に、承認認証情報が無効である、ファイルが見つからないなど、ネットワークのボリュームまたはレスポンス タイムに関係のないエラーの処理には適していません。

指数バックオフを適切に使用すると、帯域幅の使用効率が高くなり、より少ないリクエスト数で正常なレスポンスを受け取ることができ、同時実行環境でのリクエストのスループットが最大化します。

シンプルな指数バックオフを実装するフローは次のとおりです。

1. API へのリクエストを作成します。
2. リクエストの再試行が必要であることを示す HTTP 503 レスポンスを受信します。
3. 1 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
4. リクエストの再試行が必要であることを示す HTTP 503 レスポンスを受信します。
5. 2 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
6. リクエストの再試行が必要であることを示す HTTP 503 レスポンスを受信します。
7. 4 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
8. リクエストの再試行が必要であることを示す HTTP 503 レスポンスを受信します。
9. 8 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
10. リクエストの再試行が必要であることを示す HTTP 503 レスポンスを受信します。
11. 16 秒 + random_number_milliseconds の間待機してから、リクエストを再試行します。
12. フローを停止します。エラーをレポートまたはログに記録します。

上記のフローで、random_number_milliseconds は、1,000 ミリ秒以下の乱数です。この乱数は、ランダムな短い遅延を発生させることで負荷をより均等に分散し、サーバーの暴走を防ぐために必要です。random_number_milliseconds の値は、待機するたびに再定義する必要があります。

注: 待機時間は常に (2 ^ n) + random_number_milliseconds（n は 0 から始まる単調増加整数）です。整数 n は、繰り返し（リクエスト）のたびに 1 ずつ増えます。

このアルゴリズムは、n が 5 になると終了するように設定されています。この上限によって、クライアントが無限に再試行を繰り返すことを防ぎます。総遅延時間が約 32 秒になると、リクエストは「回復不能なエラー」と判断されます。再試行の最大回数を増やすこともできます（特に、長いアップロードを行う場合）。ただし、再試行の遅延時間には合理的な上限を設定してください（たとえば 1 分未満）。