BigQuery

BigQuery コネクタを使用すると、Google BigQuery データに対して挿入、削除、更新、読み取りオペレーションを実行できます。

準備

BigQuery コネクタを使用する前に、次の作業を行います。

  • Google Cloud プロジェクトで次の操作を行います。
    • ネットワーク接続が設定されていることを確認します。ネットワーク パターンの詳細については、Network Connectivity をご覧ください。
    • コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
    • コネクタに使用するサービス アカウントに、次の IAM ロールを付与します。
      • roles/bigquery.dataEditor

      サービス アカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービス アカウントがない場合は、サービス アカウントを作成する必要があります。詳細については、サービス アカウントを作成するをご覧ください。

    • 次のサービスを有効にします。
      • secretmanager.googleapis.com（Secret Manager API）
      • connectors.googleapis.com（Connectors API）

      サービスを有効にする方法については、サービスを有効にするをご覧ください。

    以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース（バックエンド システム）への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

  1. Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。

    [接続] ページに移動

  2. [+ 新規作成] をクリックして [接続の作成] ページを開きます。
  3. [ロケーション] セクションで、接続のロケーションを選択します。
    1. リージョン: プルダウン リストからロケーションを選択します

      サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。

    2. [NEXT] をクリックします。
  4. [接続の詳細] セクションで、次の操作を行います。
    1. コネクタ: 使用可能なコネクタのプルダウン リストから [BigQuery] を選択します。
    2. コネクタのバージョン: 使用可能なバージョンのプルダウン リストからコネクタのバージョンを選択します。
    3. [接続名] フィールドに、接続インスタンスの名前を入力します。

      接続名は次の条件を満たす必要があります。

      • 接続名には英字、数字、ハイフンを使用できます。
      • 文字は小文字のみを使用できます。
      • 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
      • 接続名は 49 文字以内で指定してください。
    4. 必要に応じて、接続インスタンスの [説明] を入力します。
    5. 必要に応じて、Cloud Logging を有効にして、ログレベルを選択します。デフォルトのログレベルは Error に設定されています。
    6. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
    7. 必要に応じて、接続ノードの設定を構成します。

      • ノードの最小数: 接続ノードの最小数を入力します。
      • ノードの最大数: 接続ノードの最大数を入力します。

      ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。

    8. プロジェクト ID: データが存在する Google Cloud プロジェクトの ID。
    9. データセット ID: BigQuery データセットの ID を入力します。
    10. BigQuery の ARRAY データ型をサポートするには、[ネイティブ データ型をサポートする] を選択します。次の配列型がサポートされています。
      • Varchar
      • Int64
      • Float64
      • 長い
      • Double
      • Bool
      • タイムスタンプ

      ネストされた配列はサポートされていません。

    11. Use proxy: このチェックボックスを選択して、接続用のプロキシ サーバーを構成し、次の値を構成します。
      • Proxy Auth Scheme: プロキシ サーバーで認証する認証タイプを選択します。次の認証タイプがサポートされています。
        • 基本: 基本的な HTTP 認証。
        • ダイジェスト: ダイジェスト HTTP 認証。
      • Proxy User: プロキシ サーバーでの認証に使用されるユーザー名。
      • プロキシ パスワード: ユーザーのパスワードの Secret Manager シークレット。
      • Proxy SSL Type: プロキシ サーバーへの接続時に使用する SSL タイプ。次の認証タイプがサポートされています。
        • 自動: デフォルトの設定。URL が HTTPS URL の場合は、[トンネル] オプションが使用されます。URL が HTTP URL の場合、[なし] オプションが使用されます。
        • 常に: 接続は常に SSL 対応です。
        • なし: 接続は SSL に対応していません。
        • トンネル: 接続はトンネリング プロキシ経由で行われます。プロキシ サーバーがリモートホストへの接続を開き、トラフィックはプロキシを経由するようになります。
      • [Proxy Server] セクションで、プロキシ サーバーの詳細を入力します。
        1. [+ 宛先を追加] をクリックします。
        2. [宛先の種類] を選択します。
          • Host address: 宛先のホスト名または IP アドレスを指定します。

            バックエンドへのプライベート接続を確立する場合は、次のようにします。

    12. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
    13. [NEXT] をクリックします。
  5. [認証] セクションで、認証の詳細を入力します。
    1. OAuth 2.0 - 認証コードで認証するか、認証なしで続行するかを選択します。

      認証の構成方法については、認証を構成するをご覧ください。

    2. [NEXT] をクリックします。
  6. Review: 接続と認証の詳細を確認します。
  7. [作成] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

  • 認証なし: 認証が不要な場合は、このオプションを選択します。
  • OAuth 2.0 - 認証コード: ウェブベースのユーザー ログインフローを使用して認証する場合は、このオプションを選択します。次の詳細を指定します。
    • クライアント ID: バックエンド Google サービスに接続するために必要なクライアント ID。
    • スコープ: 必要なスコープのカンマ区切りのリスト。必要な Google サービスでサポートされている OAuth 2.0 スコープを確認するには、Google API の OAuth 2.0 スコープ ページの関連セクションをご覧ください。
    • クライアント シークレット: Secret Manager のシークレットを選択します。 この認証を構成する前に、Secret Manager のシークレットを作成しておく必要があります。
    • シークレットのバージョン: クライアント シークレットの Secret Manager シークレットのバージョン。

    Authorization code 認証タイプの場合は、接続を作成した後、認証を構成するためにいくつかの追加手順を行う必要があります。詳しくは、接続作成後の追加手順をご覧ください。

接続作成後の追加手順

認証に OAuth 2.0 - Authorization code を選択した場合は、接続の作成後に次の追加の手順を行う必要があります。

  1. 接続ページで、新しく作成された接続を見つけます。

    新しいコネクタの [ステータス] は [承認が必要] になります。

  2. [承認が必要] をクリックします。

    これにより、[承認の編集] ペインが表示されます。

  3. [リダイレクト URI] の値を外部アプリケーションにコピーします。
  4. 認可の詳細を確認します。
  5. [Authorize（承認）] をクリックします。

    認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

認証コードの再認可

Authorization code 認証タイプを使用しているユーザーが、BigQuery の構成を変更した場合は、BigQuery 接続を再認証する必要があります。接続を再認可するには、次の手順を行います。

  1. [接続] ページで必要な接続をクリックします。

    これにより、[接続の詳細] ページが開きます。

  2. [編集] をクリックして、接続の詳細を編集します。
  3. [認証] セクションで [OAuth 2.0 - 認証コード] の詳細を確認します。

    必要に応じて必要な変更を加えます。

  4. [保存] をクリックします。接続の詳細ページに移動します。
  5. [認証] セクションで [承認の編集] をクリックします。これにより、[承認] ペインが表示されます。
  6. [Authorize（承認）] をクリックします。

    認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

  • エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベース コネクタでは、テーブルがエンティティであり、ファイル サーバー コネクタでは、フォルダがエンティティです。また、メッセージング システム コネクタでは、キューがエンティティです。

    ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。

  • オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。

    使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティ オペレーションをご覧ください。ただし、コネクタがいずれかのエンティティ オペレーションをサポートしていない場合、サポートされていないオペレーションは Operations リストに含まれません。

  • アクション: コネクタ インターフェースを介して統合で使用できる主要な関数の一つです。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。通常、アクションには入力パラメータと出力パラメータがあります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

システムの上限

BigQuery コネクタは、ノードごとに 1 秒あたり最大 8 件のトランザクションを処理することができ、この上限を超えるトランザクションはすべてスロットルされます。 デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます（可用性を高めるため）。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

サポートされているデータ型

このコネクタでサポートされているデータ型は次のとおりです。

  • ARRAY
  • BIGINT
  • BINARY
  • BIT
  • BOOLEAN
  • CHAR
  • DATE
  • DECIMAL
  • DOUBLE
  • FLOAT
  • INTEGER
  • LONGN VARCHAR
  • LONG VARCHAR
  • NCHAR
  • NUMERIC
  • NVARCHAR
  • REAL
  • SMALL INT
  • TIME
  • TIMESTAMP
  • TINY INT
  • VARBINARY
  • VARCHAR

既知の問題

BigQuery コネクタは、BigQuery テーブルの主キーをサポートしていません。つまり、entityId を使用してエンティティ オペレーションを取得、更新、削除することはできません。または、フィルタ句を使用して、ID に基づいてレコードをフィルタリングすることもできます。

アクション

このセクションでは、BigQuery コネクタで使用できるアクションについて説明します。

CancelJob アクション

このアクションを使用すると、実行中の BigQuery ジョブをキャンセルできます。

次の表では、CancelJob アクションの入力パラメータを示します。

パラメータ名 Data type 説明
JobId 文字列 キャンセルするジョブの ID。このフィールドは必須です。
リージョン 文字列 ジョブが現在実行されているリージョン。ジョブが米国または EU リージョンの場合、必須ではありません。

GetJob アクション

このアクションを使用すると、既存のジョブの構成情報と実行状態を取得できます。

次の表では、GetJob アクションの入力パラメータを示します。

パラメータ名 Data type 説明
JobId 文字列 構成を取得するジョブの ID。このフィールドは必須です。
リージョン 文字列 ジョブが現在実行されているリージョン。ジョブが米国または EU リージョンの場合、必須ではありません。

InsertJob アクション

このアクションを使用すると、BigQuery ジョブを挿入できます。その後、ジョブを選択してクエリ結果を取得できます。

次の表では、InsertJob アクションの入力パラメータを示します。

パラメータ名 Data type 説明
クエリ 文字列 BigQuery に送信するクエリ。このフィールドは必須です。
IsDML 文字列 クエリが DML ステートメントの場合は true に設定し、それ以外の場合は false に設定します。デフォルト値は false です。
DestinationTable 文字列 クエリの宛先テーブル（DestProjectId:DestDatasetId.DestTable 形式）。
WriteDisposition 文字列 宛先テーブルにデータを書き込む方法を指定します。既存の結果を切り捨てる、既存の結果を追加する、テーブルが空の場合にのみ書き込みを行うなどです。サポートされている値は次のとおりです。
  • WRITE_TRUNCATE
  • WRITE_APPEND
  • WRITE_EMPTY
デフォルト値は WRITE_TRUNCATE です。
DryRun 文字列 ジョブの実行がドライランかどうかを指定します。
MaximumBytesBilled 文字列 ジョブで処理できる最大バイト数を指定します。ジョブが指定された値を超えるバイト数の処理を試行すると、BigQuery はジョブをキャンセルします。
リージョン 文字列 ジョブを実行するリージョンを指定します。

InsertLoadJob アクション

このアクションを使用すると、Google Cloud Storage から既存のテーブルにデータを追加する BigQuery 読み込みジョブを挿入できます。

次の表では、InsertLoadJob アクションの入力パラメータを示します。

パラメータ名 Data type 説明
SourceURIs 文字列 Google Cloud Storage URI のスペース区切りのリスト。
SourceFormat 文字列 ファイルのソース形式。サポートされている値は次のとおりです。
  • AVRO
  • NEWLINE_DELIMITED_JSON
  • DATASTORE_BACKUP
  • PARQUET
  • ORC
  • CSV
DestinationTable 文字列 クエリの宛先テーブル（DestProjectId.DestDatasetId.DestTable 形式）。
DestinationTableProperties 文字列 テーブルのわかりやすい名前、説明、ラベルのリストを指定する JSON オブジェクト。
DestinationTableSchema 文字列 テーブルの作成に使用するフィールドを指定する JSON リスト。
DestinationEncryptionConfiguration 文字列 テーブルの KMS 暗号化設定を指定する JSON オブジェクト。
SchemaUpdateOptions 文字列 宛先テーブルのスキーマを更新するときに適用するオプションを指定する JSON リスト。
TimePartitioning 文字列 時間パーティショニングのタイプとフィールドを指定する JSON オブジェクト。
RangePartitioning 文字列 範囲パーティショニングのフィールドとバケットを指定する JSON オブジェクト。
クラスタリング 文字列 クラスタリングに使用するフィールドを指定する JSON オブジェクト。
自動検出 文字列 JSON ファイルと CSV ファイルのオプションとスキーマを自動的に決定するかどうかを指定します。
CreateDisposition 文字列 宛先テーブルが存在しない場合に宛先テーブルを作成する必要があるかどうかを指定します。サポートされている値は次のとおりです。
  • CREATE_IF_NEEDED
  • CREATE_NEVER
デフォルト値は CREATE_IF_NEEDED です。
WriteDisposition 文字列 宛先テーブルにデータを書き込む方法を指定します。既存の結果を切り捨てる、既存の結果を追加する、テーブルが空の場合にのみ書き込みを行うなどです。サポートされている値は次のとおりです。
  • WRITE_TRUNCATE
  • WRITE_APPEND
  • WRITE_EMPTY
デフォルト値は WRITE_APPEND です。
リージョン 文字列 ジョブを実行するリージョンを指定します。Google Cloud Storage リソースと BigQuery データセットの両方が同じリージョンに存在する必要があります。
DryRun 文字列 ジョブの実行がドライランかどうかを指定します。デフォルト値は false です。
MaximumBadRecords 文字列 ジョブ全体がキャンセルされる前に無効であることが許容されるレコードの数を指定します。デフォルトでは、すべてのレコードが有効である必要があります。デフォルト値は 0 です。
IgnoreUnknownValues 文字列 不明なフィールドを入力ファイルで無視するか、エラーとして処理するかを指定します。デフォルトでは、エラーとして扱われます。デフォルト値は false です。
AvroUseLogicalTypes 文字列 AVRO のデータ型を BigQuery 型に変換するために AVRO 論理型を使用する必要があるかどうかを指定します。デフォルト値は true です。
CSVSkipLeadingRows 文字列 CSV ファイルの先頭でスキップする行数を指定します。通常、ヘッダー行をスキップするために使用します。
CSVEncoding 文字列 CSV ファイルのエンコード タイプ。サポートされている値は次のとおりです。
  • ISO-8859-1
  • UTF-8
デフォルト値は UTF-8 です。
CSVNullMarker 文字列 指定すると、この文字列は CSV ファイル内の NULL 値に使用されます。デフォルトでは、CSV ファイルで NULL を使用できません。
CSVFieldDelimiter 文字列 CSV ファイル内の列を区切るために使用される文字。デフォルト値はカンマ（,）です。
CSVQuote 文字列 CSV ファイルの引用符で囲まれたフィールドに使用する文字。引用符を無効にするには、空に設定します。デフォルト値は二重引用符（"）です。
CSVAllowQuotedNewlines 文字列 CSV ファイルに引用符で囲まれたフィールド内に改行を含めることができるかどうかを指定します。デフォルト値は false です。
CSVAllowJaggedRows 文字列 CSV ファイルに欠落しているフィールドを含めることができるかどうかを指定します。デフォルト値は false です。
DSBackupProjectionFields 文字列 Cloud Datastore バックアップから読み込むフィールドの JSON リスト。
ParquetOptions 文字列 Parquet 固有のインポート オプションを指定する JSON オブジェクト。
DecimalTargetTypes 文字列 数値型に適用される優先順位を示す JSON リスト。
HivePartitioningOptions 文字列 ソース側のパーティショニング オプションを指定する JSON オブジェクト。

カスタム SQL クエリを実行する

カスタムクエリを作成する手順は次のとおりです。

  1. 詳細な手順に沿って、コネクタタスクを追加します。
  2. コネクタタスクを構成するときに、実行するアクションの種類で [Actions] を選択します。
  3. [Actions] リストで [Execute custom query] を選択し、[Done] をクリックします。

    execute-custom-query-action を示す画像 execute-custom-query-action を示す画像

  4. [Task input] セクションを開き、次の操作を行います。
    1. [タイムアウト後] フィールドに、クエリが実行されるまで待機する秒数を入力します。

      デフォルト値: 180 秒

    2. [最大行数]フィールドに、データベースから返される最大行数を入力します。

      デフォルト値: 25。

    3. カスタムクエリを更新するには、[Edit Custom Script] をクリックします。[Script editor] ダイアログが開きます。

      custom-sql-query を示す画像 custom-sql-query を示す画像

    4. [Script editor] ダイアログで、SQL クエリを入力して [Save] をクリックします。

      SQL ステートメントで疑問符（?）を使用して、クエリ パラメータ リストで指定する必要がある 1 つのパラメータを表すことができます。たとえば、次の SQL クエリは、LastName 列に指定された値と一致する Employees テーブルからすべての行を選択します。 

      SELECT * FROM Employees where LastName=?

    5. SQL クエリで疑問符を使用した場合は、各疑問符の [+ パラメータ名を追加] をクリックして、パラメータを追加する必要があります。統合の実行中に、これらのパラメータにより SQL クエリ内の疑問符（?）が順番に置き換わります。たとえば、3 つの疑問符（?）を追加した場合、3 つのパラメータを順番に追加する必要があります。

      add-query-param を示す画像 add-query-param を示す画像

      クエリ パラメータを追加する手順は次のとおりです。

      1. [Type] リストから、パラメータのデータ型を選択します。
      2. [値] フィールドに、パラメータの値を入力します。
      3. 複数のパラメータを追加するには、[+ クエリ パラメータを追加] をクリックします。

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプル テンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名 データ型 必須 説明
project_id STRING True BigQuery データセットを含むプロジェクトの ID（例: myproject）。
dataset_id STRING False プロジェクト名のない BigQuery データセットのデータセット ID（例: mydataset）。
proxy_enabled BOOLEAN False 接続用のプロキシ サーバーを構成するには、このチェックボックスをオンにします。
proxy_auth_scheme ENUM False ProxyServer プロキシへの認証に使用する認証タイプです。サポートされている値は、BASIC、DIGEST、NONE です。
proxy_user STRING False ProxyServer プロキシへの認証に使用されるユーザー名です。
proxy_password SECRET False ProxyServer プロキシの認証に使用されるパスワード。
proxy_ssltype ENUM False ProxyServer プロキシへの接続時に使用する SSL のタイプです。サポートされている値は AUTO、ALWAYS、NEVER、TUNNEL です。

統合で BigQuery 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

  • Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
  • Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

次のステップ