Salesforce データを BigQuery に読み込む

Salesforce Sales Account から BigQuery にデータを読み込むには、BigQuery Data Transfer Service for Salesforce コネクタを使用します。BigQuery Data Transfer Service を使用すると、Salesforce Sales Account から BigQuery に最新のデータを追加する定期的な転送ジョブをスケジュールできます。

制限事項

Salesforce のデータ転送には、次の制限があります。

• Salesforce コネクタは、Salesforce Sales Account からの転送のみをサポートします。
• Salesforce コネクタは、Salesforce Bulk API V1 バージョン 64.0 に含まれるフィールドのみをサポートします。以前のバージョンの Salesforce Bulk API に含まれていたフィールドの一部はサポートされていない可能性があります。Salesforce コネクタのこれらの変更の詳細については、Salesforce Bulk API をご覧ください。
• Salesforce コネクタは、Salesforce Bulk API V1 を使用して Salesforce エンドポイントに接続し、データを取得します。
  • Salesforce コネクタは、Salesforce Bulk API V1 のみを使用して Salesforce インスタンスに接続し、Salesforce Bulk API でサポートされているエンティティの転送のみをサポートします。サポートされているエンティティの詳細については、「Entity is not supported by the Bulk API」エラーをご覧ください。
• Salesforce コネクタは、バイナリ フィールドを含む次のオブジェクトの転送をサポートしていません。
  • Attachment
  • ContentVersion
  • Document
  • StaticResource
  • Scontrol
  • EmailCapture
  • MailMergeTemplate
• 定期的なデータ転送の最小間隔は 15 分です。デフォルトの定期的な転送間隔は 24 時間です。
• Salesforce の処理上限により、一度に多くのデータ転送をスケジュールすると、遅延や失敗が発生する可能性があります。Salesforce のデータ転送は、次のように制限することをおすすめします。
  • 転送構成あたりのアセット数を 10 個以下にする。
  • さまざまな転送構成で、同時に実行できる転送は 10 件までです。
• 1 つの転送構成でサポートできるデータ転送の実行は、一度に 1 回だけです。最初の転送が完了する前に 2 回目のデータ転送が実行されるようにスケジュールされている場合、最初のデータ転送のみが完了し、最初の転送と重複する他のデータ転送はスキップされます。
  • 1 つの転送構成内で転送がスキップされないようにするには、[繰り返しの頻度] を構成して、大規模なデータ転送間の時間を長くすることをおすすめします。
• 構成したネットワーク アタッチメントと仮想マシン（VM）インスタンスが異なるリージョンにある場合、Salesforce からデータを転送するときにリージョン間でデータが移動する可能性があります。

増分転送の制限事項

Salesforce の増分転送には、次の制限があります。

• ウォーターマーク列として選択できるのは TIMESTAMP 列のみです。
• 増分取り込みは、有効なウォーターマーク列があるアセットでのみサポートされます。
• ウォーターマーク列の値は単調に増加する必要があります。
• 増分転送では、ソーステーブルの削除オペレーションを同期できません。
• 1 つの転送構成でサポートできるのは、増分取り込みまたは完全取り込みのいずれかのみです。
• 最初の増分取り込みの実行後に、asset リスト内のオブジェクトを更新することはできません。
• 最初の増分取り込みの実行後に、転送構成の書き込みモードを変更することはできません。
• 最初の増分取り込みの実行後に、ウォーターマーク列または主キーを変更することはできません。

データの取り込みオプション

以降のセクションでは、Salesforce データ転送を設定する際のデータの取り込みオプションについて詳しく説明します。

完全転送または増分転送

Salesforce 転送を設定するときに、転送構成で [完全] または [増分] の書き込み設定を選択することで、BigQuery へのデータの読み込み方法を指定できます。増分転送はプレビュー版でサポートされています。

注: 増分転送に関するフィードバックまたはサポートをリクエストするには、[e-mail] にメールを送信してください。

[完全] を選択すると、データ転送のたびに Salesforce データセットからすべてのデータが転送されます。

または、[増分]（プレビュー版）を選択して、データ転送ごとにデータセット全体を読み込むのではなく、最後のデータ転送以降に変更されたデータのみを転送することもできます。データ転送で [増分] を選択した場合は、[追加] または [Upsert] の書き込みモードを指定して、データの増分転送中に BigQuery にデータを書き込む方法を定義する必要があります。以降のセクションでは、使用可能な書き込みモードについて説明します。

[追加] 書き込みモード

[追加] 書き込みモードでは、宛先テーブルに新しい行のみが挿入されます。このオプションでは、既存のレコードをチェックせずに転送されたデータが厳密に追加されるため、このモードでは宛先テーブルでデータが重複する可能性があります。

[追加] モードを選択した場合は、ウォーターマーク列を選択する必要があります。Salesforce コネクタがソーステーブルの変更を追跡するには、ウォーターマーク列が必要です。

Salesforce の転送では、レコードの作成時にのみ更新され、その後の更新では変更されない列を選択することをおすすめします。たとえば、CreatedDate 列です。

[Upsert] 書き込みモード

[Upsert] 書き込みモードでは、主キーを確認して、宛先テーブルの行を更新するか、新しい行を挿入します。主キーを指定すると、Salesforce コネクタは、宛先テーブルをソーステーブルと同期するために必要な変更を特定できます。データ転送中に指定された主キーが宛先 BigQuery テーブルに存在している場合、Salesforce コネクタはソーステーブルの新しいデータでその行を更新します。データ転送中に主キーが存在していない場合、Salesforce コネクタは新しい行を挿入します。

[Upsert] モードを選択する場合は、ウォーターマーク列と主キーを選択する必要があります。

• Salesforce コネクタがソーステーブルの変更を追跡するには、ウォーターマーク列が必要です。
  • 行が変更されるたびに更新されるウォーターマーク列を選択します。SystemModstamp 列または LastModifiedDate 列を使用することをおすすめします。

• 主キーは、行の挿入または更新が必要かどうかを Salesforce コネクタが判断するために必要なテーブルの 1 つ以上の列です。
  • テーブルのすべての行で一意の null 以外の値を含む列を選択します。システムが生成した識別子、一意の参照コード（自動増分式の ID など）、不変の時間ベースのシーケンス ID を含む列をおすすめします。
  • データの損失や破損を防ぐため、選択する主キー列には一意の値が必要です。選択した主キー列の一意性に疑問がある場合は、代わりに [追加] 書き込みモードを使用することをおすすめします。

始める前に

以降のセクションでは、Salesforce のデータ転送を作成する前に必要な手順について説明します。

Salesforce 接続アプリを作成する

次の必須構成で Salesforce 接続アプリを作成する必要があります。

• 接続アプリで基本情報を構成します。Salesforce への転送では、[Connected App Name] フィールドと [Contact Email] フィールドは必須です。
• 次の構成で OAuth 設定を有効にします。
  • [Enable OAuth Settings] チェックボックスをオンにします。
  • [URL] フィールドに、次のように入力します。
    • 本番環境の場合は、「https://login.salesforce.com/services/oauth2/token」と入力します。
    • サンドボックス環境の場合は、「https://test.salesforce.com/services/oauth2/token」と入力します。
  • [Issue JSON Web Token(JWT)-based access tokens for named users] チェックボックスが選択されていないことを確認します。
• [Selected OAuth Scopes] セクションで、[Manage user data via APIs (api)] を選択します。
• [Required Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows] チェックボックスをオフにします。
• [Enable Client Credentials Flow] を選択し、表示された通知で [OK] をクリックします。

必要な構成で接続アプリを構成したら、[Save] をクリックします。新しく作成した接続アプリの詳細ページにリダイレクトされます。

接続アプリを作成したら、次の手順でクライアント認証情報フローを構成する必要があります。

1. [Setup] をクリックします。
2. 検索バーで「Connected Apps」を検索します。
3. [Manage Apps] > [Connected Apps] をクリックします。Salesforce Lightning Experience を使用している場合は、[Manage Connected Apps] をクリックします。
4. 作成した接続アプリで [Edit] をクリックします。
5. [App details] ページが表示されます。[Client Credentials Flow] セクションの [Run As] フィールドにユーザー名を入力します。このフィールドの検索ツールを使用して、正しいユーザーを選択していることを確認できます。
6. [保存] をクリックします。

必要な Salesforce 情報

Salesforce のデータ転送を作成する場合は、Salesforce について次の情報も用意する必要があります。

パラメータ名	説明
myDomain	Salesforce の My Domain。
clientId	Salesforce 接続アプリケーションのコンシューマー キー。
clientSecret	Salesforce 接続アプリケーションの OAuth クライアント シークレットまたはコンシューマー シークレット。

myDomain、clientID、clientSecret の値を取得するには、次のいずれかのオプションを選択します。

Salesforce Classic

myDomain の詳細を取得する

myDomain を確認する手順は次のとおりです。

1. Salesforce プラットフォームにログインします。
2. [Setup] をクリックします。
3. 検索バーで「My Domain」を検索します。
4. 検索結果で、[Domain Management] > [My Domain] をクリックします。

[My Domain Details] セクションの [Current My Domain URL] に、myDomain がプレフィックスとして表示されます。たとえば、マイドメインの URL が example.my.salesforce.com の場合、使用する myDomain の値は example です。

ClientId と ClientSecret の詳細を取得する

ClientId と ClientSecret の値を確認する手順は次のとおりです。

1. Salesforce プラットフォームにログインします。
2. [Setup] をクリックします。
3. 検索バーで「Apps」を検索します。
4. 検索結果の [Build] セクションで、[Create] > [Apps] をクリックします。
5. [Connected App Name] をクリックします。
6. [Connected Apps] の詳細ページで、[Manage Consumer Details] をクリックします。
7. 登録済みのいずれかの方法で本人確認を行います。本人確認を再度行うよう求められるまで、最大 5 分間、お客様の詳細ページを表示できます。
8. [Consumer Details] ページの [Consumer Key] が ClientId の値です。[Customer Secret] は ClientSecret の値です。

Salesforce Lightning Experience

myDomain の詳細を取得する

myDomain を確認する手順は次のとおりです。

1. Salesforce プラットフォームにログインします。
2. [Setup] をクリックします。

1. 検索バーで「My Domain」を検索します。
2. 検索結果で、[Company Settings] > [My Domain] をクリックします。

[My Domain Details] セクションの [Current My Domain URL] に、myDomain がプレフィックスとして表示されます。たとえば、マイドメインの URL が example.my.salesforce.com の場合、使用する myDomain の値は example です。

ClientId と ClientSecret の詳細を取得する

1. Salesforce プラットフォームにログインします。
2. [Setup] をクリックします。
3. 検索バーで「Apps」を検索します。
4. 検索結果で [Apps] > [App Manager] をクリックします。
5. 接続済みのアプリを見つけて、[View] をクリックします。
6. [Manage Consumer Details] をクリックします。
7. 登録済みのいずれかの方法で本人確認を行います。本人確認を再度行うよう求められるまで、最大 5 分間、お客様の詳細ページを表示できます。
8. [Consumer Details] ページの [Consumer Key] が ClientId の値です。[Customer Secret] は ClientSecret の値です。

Salesforce 転送の IP 許可リストを設定する

データ転送の許可リストに特定の IP アドレスを追加するには、 Google Cloud 環境と Salesforce アカウントを構成する必要があります。これにより、Salesforce は信頼できる静的 IP アドレスからの接続のみを受け入れるようになります。

これを行うには、まず静的 IP アドレスを使用するように Google Cloud ネットワークを設定して構成する必要があります。

1. Virtual Private Cloud ネットワーク内の静的 IP アドレスを使用して、パブリック ネットワーク アドレス変換（NAT）を設定します。CloudNAT は、このデータ転送の宛先データセットと同じリージョン内で構成する必要があります。
2. 同じ VPC ネットワーク内にネットワーク アタッチメントを設定します。このリソースは、BigQuery Data Transfer Service が限定公開サービスにアクセスするために使用されます。

次に、Salesforce で信頼できる IP 範囲を構成する必要があります。IP アドレスの範囲を追加するときは、Google Cloud Public NAT の静的 IP アドレスを IP 範囲の開始 IP アドレスと終了 IP アドレスの両方に使用します。

注: よりきめ細かく制御するには、プロファイル レベルまたは API 呼び出しごとに IP 制限を適用します。詳細については、プロファイルでログイン IP アドレスを制限するをご覧ください。

IP 範囲を設定したら、[ネットワーク アタッチメント] フィールドでネットワーク アタッチメントを選択して、転送構成を設定するときに静的 IP を指定できます。

BigQuery の前提条件

• BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
• データを保存する BigQuery データセットを作成します。
• Pub/Sub の転送実行通知を設定する場合は、pubsub.topics.setIamPolicy Identity and Access Management（IAM）権限があることを確認します。メール通知を設定するだけの場合、Pub/Sub の権限は必要ありません。詳細については、BigQuery Data Transfer Service の実行通知をご覧ください。

必要な BigQuery のロール

BigQuery Data Transfer Service データ転送の作成に必要な権限を取得するには、プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）IAM ロールを付与するよう管理者に依頼します。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、BigQuery Data Transfer Service のデータ転送の作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

BigQuery Data Transfer Service のデータ転送を作成するには、次の権限が必要です。

• BigQuery Data Transfer Service の権限
  • bigquery.transfers.update
  • bigquery.transfers.get
• BigQuery の権限
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
  • bigquery.jobs.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

詳細については、bigquery.admin のアクセス権を付与するをご覧ください。

Salesforce のデータ転送を設定する

次のいずれかのオプションを使用して転送構成を設定し、Salesforce データを BigQuery に追加します。

コンソール

1. Google Cloud コンソールの [データ転送] ページに移動します。

   [データ転送] に移動

2. [転送を作成] をクリックします。

3. [ソースタイプ] セクションの [ソース] で、[Salesforce] を選択します。

4. [データソースの詳細] セクションで、次のようにします。

   • [ネットワーク アタッチメント] で、リストからネットワーク アタッチメントを選択します。詳細については、Salesforce 転送の IP 許可リストを設定するをご覧ください。
   • [My Domain] に Salesforce の My Domain を入力します。
   • [クライアント ID] に、Salesforce 接続アプリケーションのコンシューマ キーを入力します。
   • [クライアント シークレット] に、Salesforce 接続アプリケーションのコンシューマ シークレットを入力します。
   • [取り込みタイプ] で、[完全] または [増分] を選択します。
     • [増分]（プレビュー版）を選択した場合は、[書き込みモード] で [追加] または [Upsert] を選択します。書き込みモードの詳細については、完全転送または増分転送をご覧ください。
   • [Salesforce objects to transfer] で、[参照] をクリックします。
     • BigQuery 宛先データセットに転送するオブジェクトを選択します。このフィールドには、データ転送に含めるオブジェクトを手動で入力することもできます。
     • 増分書き込みモードとして [追加] を選択した場合は、列をウォーターマーク列として選択する必要があります。
     • 増分書き込みモードとして [Upsert] を選択した場合は、列をウォーターマーク列として選択し、1 つ以上の列を主キーとして選択する必要があります。

5. [転送先の設定] セクションの [データセット] で、データを保存するために作成したデータセットを選択します。

6. [転送構成名] セクションの [表示名] に、データ転送の名前を入力します。

7. [スケジュール オプション] セクションで:

   • [繰り返しの頻度] リストで、この転送の実行頻度を指定するオプションを選択します。カスタムの繰り返しの頻度を指定するには、[カスタム] を選択します。[オンデマンド] を選択した場合、手動で転送をトリガーすると、この転送が実行されます。
   • 必要に応じて、[すぐに開始] を選択するか、[設定した時刻に開始] を選択して開始日と実行時間を指定します。

8. 省略可: [通知オプション] セクションで、次のようにします。

   • メール通知を有効にするには、[メール通知] をクリックします。このオプションを有効にすると、転送の実行が失敗した場合、転送管理者にメール通知が送信されます。
   • この転送の Pub/Sub 転送実行通知を有効にするには、[Pub/Sub 通知] をクリックします。トピック名を選択するか、[トピックを作成する] をクリックしてトピックを作成します。

9. [保存] をクリックします。

bq

bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

各パラメータの説明は次のとおりです。

• PROJECT_ID（省略可）: Google Cloud プロジェクト ID。--project_id で特定のプロジェクトを指定しない場合は、デフォルトのプロジェクトが使用されます。
• DATA_SOURCE: データソース - salesforce。
• NAME: データ転送構成の表示名。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
• DATASET: 転送構成のターゲット データセット。

• PARAMETERS: 作成される転送構成のパラメータを JSON 形式で指定します。例: --params='{"param":"param_value"}'。Salesforce データ転送のパラメータは次のとおりです。

  • connector.authentication.oauth.clientId: Salesforce 接続アプリケーションのコンシューマー キー。
  • connector.authentication.oauth.clientSecret: Salesforce 接続アプリケーションの OAuth クライアント シークレットまたはコンシューマー シークレット。
  • connector.authentication.oauth.myDomain: Salesforce My Domain。たとえば、ドメインの URL が example.my.salesforce.com の場合、値は example です。
  • ingestionType: FULL または INCREMENTAL を指定します。増分転送はプレビュー版でサポートされています。詳細については、完全転送または増分転送をご覧ください。
  • writeMode: WRITE_MODE_APPEND または WRITE_MODE_UPSERT を指定します。
  • watermarkColumns: テーブル内の列をウォーターマーク列として指定します。このフィールドは増分転送の場合に必須です。
  • primaryKeys: テーブルの列を主キーとして指定します。このフィールドは増分転送の場合に必須です。
  • assets: BigQuery に転送する Salesforce オブジェクトのパス。

増分転送中に複数のアセットを指定する場合、watermarkColumns フィールドと primaryKeys フィールドの値は、assets フィールドの値の位置に対応します。次の例では、Id はテーブル Account に対応し、master_label と type はテーブル CaseHistory に対応します。

      "primaryKeys":[['Id'], ['master_label','type']],
      "assets":["Account","CaseHistory"],
  

次のコマンドは、デフォルト プロジェクトに増分 Salesforce データ転送を作成し、APPEND 書き込みモードを使用します。

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=salesforce
    --display_name='My Transfer'
    --params='{"assets": ["Account", "CaseHistory"]
        "connector.authentication.oauth.clientId": "1234567890",
        "connector.authentication.oauth.clientSecret":"ABC12345",
        "connector.authentication.oauth.myDomain":"MyDomainName",
        "connector.authentication.username":"[e-mail]",
        "connector.authentication.password":"abcdef1234",
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_UPSERT",
        "watermarkColumns":["SystemModstamp","CreatedDate"]
        "primaryKeys":[['Id'], ['master_label','type']]}'

API

projects.locations.transferConfigs.create メソッドを使用して、TransferConfig リソースのインスタンスを指定します。

転送構成を保存すると、Salesforce コネクタはスケジュール オプションに従って転送実行を自動的にトリガーします。転送を実行するたびに、Salesforce コネクタは Salesforce から BigQuery に使用可能なすべてのデータを転送します。

定期的なスケジュール外でデータ転送を手動で実行するには、バックフィル実行を開始します。

データ型マッピング

次の表に、Salesforce のデータ型と対応する BigQuery データ型を示します。

Salesforce のデータ型	BigQuery のデータ型
_bool	BOOLEAN
_int	INTEGER
_long	INTEGER
_double	FLOAT
currency	FLOAT
percent	FLOAT
geolocation (latitude)	FLOAT
geolocation (longitude)	FLOAT
date	DATE
datetime	TIMESTAMP
time	TIME
picklist	STRING
multipicklist	STRING
combobox	STRING
reference	STRING
base64	STRING
textarea	STRING
phone	STRING
id	STRING
url	STRING
email	STRING
encryptedstring	STRING
datacategorygroupreference	STRING
location	STRING
address	STRING
anyType	STRING

料金

Salesforce 転送の料金については、Data Transfer Service の料金をご覧ください。

転送の設定に関するトラブルシューティング

データ転送の設定で問題が発生した場合は、Salesforce の転送に関する問題をご覧ください。

次のステップ

• BigQuery Data Transfer Service の概要については、BigQuery Data Transfer Service の概要をご覧ください。
• 転送構成に関する情報の取得、転送構成の一覧表示、転送の実行履歴の表示など、転送の使用方法については、転送の操作をご覧ください。
• クロスクラウドの操作でデータを読み込む方法を学習する。