Blob Storage に接続する

BigQuery 管理者は、接続を作成して、データアナリストが Azure Blob Storage に保存されているデータにアクセスできるようにします。

BigQuery Omni は、接続を介して Blob Storage のデータにアクセスします。BigQuery Omni は、Azure Workload Identity 連携をサポートしています。BigQuery Omni で Azure Workload Identity 連携がサポートされているため、テナント内の Azure アプリケーションに Google サービスアカウントへのアクセス権を付与できます。ユーザーまたは Google が管理するアプリケーションクライアントシークレットはありません。

BigQuery Azure 接続を作成したら、Blob Storage データに対してクエリを実行できます。また、クエリ結果を Blob Storage にエクスポートすることもできます。

始める前に

以下のリソースが作成されていることを確認します。
- BigQuery Connection API が有効になっている Google Cloud プロジェクト。
- 容量ベースの料金モデルを使用している場合は、プロジェクトで BigQuery Reservation API が有効になっていることを確認します。料金については、BigQuery Omni の料金をご覧ください。
- Azure サブスクリプションが付属した Azure テナント。
- 次の仕様を満たす Azure Storage アカウント。
  - 汎用 V2 アカウントまたは Blob Storage アカウント。
  - 階層型名前空間を使用していること。詳細については、Azure Data Lake Storage Gen2 で使用するストレージアカウントを作成するをご覧ください。
  - データが、サポートされている形式のいずれかで入力されていること。
  - データが azure-eastus2 リージョンにあること。

必要なロール

Azure Blob Storage のデータにアクセスするための接続の作成に必要な権限を取得するには、プロジェクトに対する BigQuery Connection 管理者（roles/bigquery.connectionAdmin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
テナントに次の Azure IAM 権限があることを確認します。
- Application.ReadWrite.All
- AppRoleAssignment.ReadWrite.All

割り当て

割り当ての詳細については、BigQuery Connection API をご覧ください。

Azure 接続を作成する

Azure 接続を作成する手順は次のとおりです。

Azure テナントでアプリケーションを作成します。
BigQuery Azure 接続を作成します。
連携認証情報を追加します。
BigQuery Azure AD アプリケーションにロールを割り当てます。

連携 ID 認証情報を使用して Azure データにアクセスする方法については、Workload Identity 連携をご覧ください。

Azure テナントにアプリケーションを作成する

Azure テナントにアプリケーションを作成するには、次の手順を実行します。

Azure Portal

Azure Portal で、[アプリの登録] に移動し、[新規登録] をクリックします。
[名前] にアプリケーションの名前を入力します。
[サポートされているアカウントの種類] で、[Accounts in this organizational directory only] を選択します。
新しいアプリケーションを登録するには、[登録] をクリックします。
アプリケーション（クライアント）ID をメモします。接続を作成するときに、この ID を指定する必要があります。

Terraform

Terraform 構成ファイルに以下を追加します。

  resource "azuread_application" "example" {
    display_name = "bigquery-omni-connector"
  }

  resource "azuread_service_principal" "example" {
    application_id               = azuread_application.example.application_id
    app_role_assignment_required = false
  }

詳細については、Azure でアプリケーションを登録する方法をご覧ください。

接続を作成する

コンソール

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動
[ データを追加] メニューで [外部データソース] を選択します。
[外部データソース] ペインで、次の情報を入力します。
- [接続タイプ] で、[Azure 上の BigLake（BigQuery Omni 経由）] を選択します。
- [接続 ID] に、接続リソースの識別子を入力します。文字、数字、ダッシュ、アンダースコアを使用できます。
- 接続を作成するロケーションを選択します。
- （省略可）: [Friendly name] に、わかりやすい接続名を入力します（例: My connection resource）。後で修正が必要になった場合、わかりやすい名前だと接続リソースを簡単に識別できます。
- （省略可）: [説明] に、この接続リソースの説明を入力します。
- [Azure テナント ID] に Azure テナント ID を入力します。これは、ディレクトリ（テナント）ID とも呼ばれます。
- [フェデレーション ID を使用する] チェックボックスをオンにして、Azure 連携アプリケーション（クライアント）ID を入力します。
  
  Azure ID を取得する方法について詳しくは、Azure テナントでアプリケーションを作成するをご覧ください。
[接続を作成] をクリックします。
[接続へ移動] をクリックします。
[接続情報] セクションで、[BigQuery Google ID] の値をメモします。これはサービスアカウント ID です。この ID は、アプリケーションへのアクセスを承認する Google Cloud サービスアカウント用です。

Terraform

  resource "google_bigquery_connection" "connection" {
    connection_id = "omni-azure-connection"
    location      = "azure-eastus2"
    description   = "created by terraform"

    azure {
      customer_tenant_id              = "TENANT_ID"
      federated_application_client_id = azuread_application.example.application_id
    }
  }

TENANT_ID は、Blob Storage アカウントを含む Azure ディレクトリのテナント ID に置き換えます。

bq

bq mk コマンドを使用します。JSON 形式で出力を取得するには、--format=json パラメータを使用します。

bq mk --connection --connection_type='Azure' \
  --tenant_id=TENANT_ID \
  --location=AZURE_LOCATION \
  --federated_azure=true \
  --federated_app_client_id=APP_ID \
  CONNECTION_ID

次のように置き換えます。

TENANT_ID: Azure Storage アカウントを含む Azure ディレクトリのテナント ID。
AZURE_LOCATION: Azure Storage データが配置されている Azure リージョン。BigQuery Omni は azure-eastus2 リージョンをサポートしています。
APP_ID: Azure アプリケーション（クライアント）ID。この ID を取得する方法については、Azure テナントでアプリケーションを作成するをご覧ください。
CONNECTION_ID: 接続の名前。

出力は次のようになります。

Connection CONNECTION_ID successfully created
Please add the following identity to your Azure application APP_ID
Identity: SUBJECT_ID

この出力には次の値が含まれます。

APP_ID: 作成したアプリケーションの ID。
SUBJECT_ID: ユーザーがアプリケーションへのアクセスを承認するための Google Cloud サービスアカウントの ID。この値は、Azure で連携認証情報を作成する場合に必要です。

次のステップで使用するために、APP_ID と SUBJECT_ID の値をメモしておきます。

次に、アプリケーションの連携認証情報を追加します。

連携認証情報を追加する

連携認証情報を作成する手順は次のとおりです。

Azure Portal

Azure Portal で、[アプリの登録] に移動し、アプリケーションをクリックします。
[証明書とシークレット] > [連携認証情報] > [認証情報を追加] を選択します。次に、以下の操作を行います。
1. 連携認証情報のシナリオリストから、[その他の発行元] を選択します。
2. [発行元] に「https://accounts.google.com」と入力します。
3. [Subject identifier] に、接続の作成時に取得した Google Cloud サービスアカウントの BigQuery Google ID を入力します。
4. [名前] に認証情報の名前を入力します。
5. [追加] をクリックします。

Terraform

Terraform 構成ファイルに以下を追加します。

  resource "azuread_application" "example" {
    display_name = "bigquery-omni-connector"
  }

  resource "azuread_service_principal" "example" {
    application_id               = azuread_application.example.application_id
    app_role_assignment_required = false
  }

  resource "azuread_application_federated_identity_credential" "example" {
    application_object_id = azuread_application.example.object_id
    display_name          = "omni-federated-credential"
    description           = "BigQuery Omni federated credential"
    audiences             = ["api://AzureADTokenExchange"]
    issuer                = "https://accounts.google.com"
    subject               = google_bigquery_connection.connection.azure[0].identity
  }

詳細については、外部 ID プロバイダを信頼するようにアプリを構成するをご覧ください。

BigQuery の Azure アプリケーションにロールを割り当てる

BigQuery の Azure アプリケーションにロールを割り当てるには、Azure Portal、Azure PowerShell、または Microsoft Management REST API を使用します。

Azure Portal

Azure Portal でロールを割り当てるには、Microsoft.Authorization/roleAssignments/write 権限を持つユーザーとしてログインします。ロールの割り当てにより、BigQuery Azure 接続が、ロールポリシーで指定された Azure Storage データにアクセスできます。

Azure Portal を使用してロールの割り当てを追加する手順は次のとおりです。

Azure Storage アカウントの検索バーに「IAM」と入力します。
[アクセス制御（IAM）] をクリックします。
[追加] をクリックし、[Add role assignments] を選択します。
読み取り専用権限を付与するには、[Storage Blob Data Reader] ロールを選択します。読み取り / 書き込みアクセスを付与するには、[Storage Blob Data Contributor] ロールを選択します。
[Assign access to] を [User, group, or service principal] に設定します。
[メンバーを選択] をクリックします。
[選択] フィールドに、Azure テナントでアプリケーションを作成したときに指定した Azure アプリケーション名を入力します。
[保存] をクリックします。

詳細については、Azure ポータルを使用して Azure ロールを割り当てるをご覧ください。

Terraform

Terraform 構成ファイルに以下を追加します。

  resource "azurerm_role_assignment" "data-role" {
    scope                = data.azurerm_storage_account.example.id
    # Read permission for Omni on the storage account
    role_definition_name = "Storage Blob Data Reader"
    principal_id         = azuread_service_principal.example.id
  }

Azure PowerShell

リソーススコープでのサービスプリンシパルのロールの割り当てを追加するには、New-AzRoleAssignment コマンドを使用します。

  New-AzRoleAssignment`
   -SignInName APP_NAME`
   -RoleDefinitionName ROLE_NAME`
   -ResourceName RESOURCE_NAME`
   -ResourceType RESOURCE_TYPE`
   -ParentResource PARENT_RESOURCE`
   -ResourceGroupName RESOURCE_GROUP_NAME

次のように置き換えます。

APP_NAME: アプリの名前。
ROLE_NAME: 割り当てるロール名。
RESOURCE_NAME: リソース名。
RESOURCE_TYPE: リソースの型。
PARENT_RESOURCE: 親リソース。
RESOURCE_GROUP_NAME: リソースグループ名。

Azure PowerShell を使用して新しいサービスプリンシパルを追加する方法については、Azure PowerShell を使用して Azure ロールを割り当てるをご覧ください。

Azure CLI

リソーススコープでのサービスプリンシパルのロールの割り当てを追加するには、Azure コマンドラインツールを使用します。ロールを付与するには、ストレージアカウントに Microsoft.Authorization/roleAssignments/write 権限が必要です。

Storage Blob Data Reader などのロールをサービスプリンシパルに割り当てるには、az role assignment create コマンドを実行します。

  az role assignment create --role "Storage Blob Data Reader" \
    --assignee-object-id ${SP_ID} \
    --assignee-principal-type ServicePrincipal \
    --scope   subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME/providers/Microsoft.Storage/storageAccounts/STORAGE_ACCOUNT_NAME

次のように置き換えます。

SP_ID: サービスプリンシパル ID。このサービスプリンシパルは、作成したアプリケーション用です。連携接続のサービスプリンシパルを取得するには、サービスプリンシパルオブジェクトをご覧ください。
STORAGE_ACCOUNT_NAME: ストレージアカウント名。
RESOURCE_GROUP_NAME: リソースグループ名。
SUBSCRIPTION_ID: サブスクリプション ID。

詳細については、Azure CLI を使用して Azure ロールを割り当てるをご覧ください。

Microsoft REST API

サービスプリンシパルのロールの割り当てを追加するには、HTTP リクエストを Microsoft Management に送信します。

Microsoft Graph REST API を呼び出すには、アプリケーションの OAuth トークンを取得します。詳しくは、ユーザーなしでアクセス権を取得するをご覧ください。Microsoft Graph REST API を呼び出すアプリケーションには、Application.ReadWrite.All アプリケーション権限が必要です。

OAuth トークンを生成するには、次のコマンドを実行します。

  export TOKEN=$(curl -X POST \
    https://login.microsoftonline.com/TENANT_ID/oauth2/token \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "resource=https://graph.microsoft.com/" \
    --data-urlencode "client_id=CLIENT_ID" \
    --data-urlencode "client_secret=CLIENT_SECRET" \
  | jq --raw-output '.access_token')

次のように置き換えます。

TENANT_ID: テナント ID は、Azure Storage アカウントを含む Azure ディレクトリの ID と一致します。
CLIENT_ID: Azure クライアント ID。
CLIENT_SECRET: Azure クライアントシークレット。

サービスプリンシパルに割り当てる Azure 組み込みのロールの ID を取得します。

一般的なロールは次のとおりです。

Storage Blob Data Contributor: ba92f5b4-2d11-453d-a403-e96b0029c9fe
Storage Blob Data Reader: 2a2b9908-6ea1-4ae2-8e65-a410df84e7d1

サービスプリンシパルにロールを割り当てるには、Azure Resource Management REST API に対して Microsoft Graph REST API を呼び出します。

  export ROLE_ASSIGNMENT_ID=$(uuidgen)
  curl -X PUT \
'https://management.azure.com/subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME/providers/Microsoft.Storage/storageAccounts/STORAGE_ACCOUNT_NAME/providers/Microsoft.Authorization/roleAssignments/ROLE_ASSIGNMENT_ID?api-version=2018-01-01-preview' \
    -H "authorization: Bearer ${TOKEN?}" \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/json' \
    -d '{
        "properties": {
            "roleDefinitionId": "subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME/providers/Microsoft.Storage/storageAccounts/STORAGE_ACCOUNT_NAME/providers/Microsoft.Authorization/roleDefinitions/ROLE_ID",
            "principalId": "SP_ID"
        }
    }'

次のように置き換えます。

ROLE_ASSIGNMENT_ID: ロール ID。
SP_ID: サービスプリンシパル ID。このサービスプリンシパルは、作成したアプリケーション用です。連携接続のサービスプリンシパルを取得するには、サービスプリンシパルオブジェクトをご覧ください。
SUBSCRIPTION_ID: サブスクリプション ID。
RESOURCE_GROUP_NAME: リソースグループ名。
STORAGE_ACCOUNT_NAME: ストレージアカウント名。
SUBSCRIPTION_ID: サブスクリプション ID。

これで接続が使用できるようになりました。ただし、Azure でのロールの割り当てが反映されるまでに時間がかかることがあります。権限の問題により接続を使用できない場合は、しばらくしてから再度お試しください。

ユーザーと接続を共有する

次のロールを付与することで、ユーザーがデータをクエリして接続を管理できます。

roles/bigquery.connectionUser: ユーザーが接続を使用して外部データソースに接続し、クエリを実行できるようにします。
roles/bigquery.connectionAdmin: ユーザーが接続を管理できるようにします。

BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。

次のオプションのいずれかを選択します。

コンソール

[BigQuery] ページに移動します。

[BigQuery] に移動

接続は、プロジェクトで外部接続というグループに一覧表示されます。
[エクスプローラ] ペインで、[プロジェクト名] > [外部接続] > [接続] の順にクリックします。
[詳細] ペインで、[共有] をクリックして接続を共有します。次に、以下の操作を行います。
1. [接続の権限] ダイアログで、プリンシパルを追加または編集して、他のプリンシパルと接続を共有します。
2. [保存] をクリックします。

bq

bq コマンドラインツールを使用して接続を共有することはできません。接続を共有するには、Google Cloud コンソールまたは BigQuery Connections API メソッドを使用します。

API

BigQuery Connections REST API の projects.locations.connections.setIAM メソッドを使用して、policy リソースのインスタンスを指定します。

Java

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

次のステップ

さまざまな接続タイプについて確認する。
接続の管理について確認する。
BigQuery Omni について確認する。
BigLake テーブルについて確認する。
Blob Storage データに対してクエリを実行する方法を確認する。
クエリ結果を Blob Storage にエクスポートする方法を確認する。