Azure Data Factory または Azure Synapse Analytics を使用して Salesforce との間でデータをコピーする

[アーティクル]
04/20/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

この記事では、Azure Data Factory と Azure Synapse パイプラインのコピーアクティビティを使用して、Salesforce 間でデータをコピーする方法について説明します。この記事は、コピーアクティビティの概要を示しているコピーアクティビティの概要に関する記事に基づいています。

重要

新しい Salesforce コネクタにより、ネイティブの Salesforce サポートが強化されます。下位互換性のためにのみ現状のままサポートされているレガシ Salesforce コネクタをソリューションで使用している場合は、Salesforce コネクタ (レガシ)に関する記事を参照してください。

サポートされる機能

この Salesforce コネクタは、次の機能でサポートされています。

サポートされる機能	IR
Copy アクティビティ (ソース/シンク)	① ②
Lookup アクティビティ	① ②

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

ソースまたはシンクとしてサポートされているデータストアの一覧については、サポートされるデータストアに関する表を参照してください。

具体的には、この Salesforce コネクタは以下をサポートします。

Salesforce Developer、Professional、Enterprise、または Unlimited エディション。
カスタムドメインとの間でデータのコピー (カスタムドメインは運用環境とサンドボックス環境の両方で構成できます)。

リンクサービスで apiVersion プロパティを使用して、データの読み取りまたは書き込みに使用する API バージョンを明示的に設定することができます。 Salesforce へのデータのコピー時に、コネクタでは BULK API 2.0 が使用されます。

前提条件

Salesforce で API アクセス許可を有効にする必要があります。
この公式ドキュメントを参照するか、この記事の推奨事項のステップバイステップガイドラインを参照して、Salesforce ポータルで接続アプリを構成する必要があります。
重要
- 実行ユーザーには "API のみ" のアクセス許可が必要です。
- アクセストークンの有効期限は、更新トークンではなくセッションポリシーを使用して変更できます。

Salesforce Bulk API 2.0 の制限

Salesforce Bulk API 2.0 を使用して、データのクエリと取り込みを行います。 Bulk API 2.0 では、バッチが自動的に作成されます。 24 時間のロール期間あたり最大 15,000 件のバッチを送信できます。バッチが上限を超えると、エラーが表示されます。

Bulk API 2.0 では、取り込みジョブのみがバッチを使用します。クエリジョブは使用しません。詳細については、「Bulk API 2.0 Developer Guide (Bulk API 2.0 開発者ガイド)」の「How Requests Are Processed」(要求の処理方法) を参照してください。

詳細については、Salesforce Developer の制限に関する資料の「General Limits」(一般的な制限) を参照してください。

作業の開始

パイプラインでコピーアクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。

UI を使用して Salesforce にリンクサービスを作成する

次の手順を使用して、Azure portal の UI で Salesforce にリンクサービスを作成します。

Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクされたサービス] を選択して、[新規] をクリックします。
- Azure Data Factory
- Azure Synapse
Salesforce を検索し、Salesforce コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

次のセクションでは、Salesforce コネクタに固有のエンティティの定義に使用されるプロパティについて詳しく説明します。

リンクされたサービスのプロパティ

Salesforce のリンクされたサービスでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	type プロパティは SalesforceV2 に設定する必要があります。	はい
environmentUrl	Salesforce インスタンスの URL を指定します。たとえば、カスタムドメインからデータをコピーするには、`"https://<domainName>.my.salesforce.com"` を指定します。カスタムドメインを構成または表示する方法については、こちらの記事を参照してください。	はい
authenticationType	Salesforce への接続に使用される認証の種類です。使用できる値は OAuth2ClientCredentials です。	はい
clientId	Salesforce OAuth 2.0 接続アプリのクライアント ID を指定します。詳細については、こちらの記事を参照してください	はい
clientSecret	Salesforce OAuth 2.0 接続アプリのクライアントシークレットを指定します。詳細については、こちらの記事を参照してください	はい
apiVersion	使用する Salesforce Bulk API 2.0 のバージョンを指定します (例: `52.0`)。 Bulk API 2.0 では、API バージョン 47.0 以降のみがサポートされています。 Bulk API 2.0 のバージョンについては、記事を参照してください。より低いバージョンの API を使用すると、エラーが発生します。	はい
connectVia	データストアに接続するために使用される統合ランタイム。指定されていない場合は、既定の Azure 統合ランタイムが使用されます。	いいえ

例: 資格情報を格納する

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例:Key Vault に資格情報を格納する

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client secret in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例: environmentUrl と clientId に加えて資格情報も Key Vault に格納する

これを行うことで、UI を使用して設定を編集できなくなることに注意してください。 [JSON 形式で動的コンテンツを指定する] チェックボックスがオンになります。この構成を完全に手動で編集することが必要になります。利点は、ここで何かをパラメーター化するのではなく、Key Vault からすべての構成設定を派生させることができることです。

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client ID in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "clientSecret": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client secret in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

データセットのプロパティ

データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。このセクションでは、Salesforce データセットでサポートされるプロパティの一覧を示します。

Salesforce との間でデータをコピーするには、データセットの type プロパティを SalesforceV2Object に設定します。次のプロパティがサポートされています。

プロパティ	内容	必須
type	type プロパティは SalesforceV2Object に設定する必要があります。	はい
objectApiName	データの取得元の Salesforce オブジェクト名。	ソースの場合はいいえ (ソースの "SOQLQuery" が指定されている場合)、シンクの場合ははい
reportId	データの取得先である Salesforce レポートの ID。シンクではサポートされていません。レポートを使用する場合は制限があることに注意してください。	ソースの場合はいいえ (ソースの "SOQLQuery" が指定されている場合)、シンクはサポートされていません

重要

カスタムオブジェクトには、API 名の "__c" の部分が必要となります。

Salesforce 接続 API 名

例:

{
    "name": "SalesforceDataset",
    "properties": {
        "type": "SalesforceV2Object",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

コピーアクティビティのプロパティ

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。このセクションでは、Salesforce ソースとシンクでサポートされるプロパティの一覧を示します。

ソースタイプとしての Salesforce

Salesforce からデータをコピーするには、コピーアクティビティのソースの種類を SalesforceV2Source に設定します。コピーアクティビティの source セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	コピーアクティビティのソースの type プロパティは SalesforceV2Source に設定する必要があります。	はい
SOQLQuery	カスタムクエリを使用してデータを読み取ります。 Salesforce オブジェクトクエリ言語 (SOQL) クエリのみを使用できますが、制限があります。 SOQL の制限については、この記事を参照してください。クエリを指定しない場合は、データセット内の "ObjectApiName/reportId" で指定された Salesforce オブジェクトのすべてのデータが取得されます。	いいえ (データセットの "ObjectApiName/reportId" が指定されている場合)
includeDeletedObjects	既存のレコード、または削除されたものを含むすべてのレコードの、どちらのクエリを行うかを示します。指定しない場合、既定の動作は false です。使用可能な値: false (既定値)、true。	いいえ

重要

カスタムオブジェクトには、API 名の "__c" の部分が必要となります。

Salesforce 接続 API 名一覧

例:

"activities":[
    {
        "name": "CopyFromSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceV2Source",
                "SOQLQuery": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c",
                "includeDeletedObjects": false
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

シンクの種類としての Salesforce

Salesforce にデータをコピーするには、コピーアクティビティのシンクの種類を SalesforceV2Sink に設定します。コピーアクティビティの sink セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	コピーアクティビティのシンクの type プロパティは SalesforceV2Sink に設定する必要があります。	はい
writeBehavior	操作の書き込み動作。使用可能な値: Insert および Upsert。	いいえ (既定値は Insert)
externalIdFieldName	Upsert 操作の外部 ID フィールドの名前。指定するフィールドは、Salesforce オブジェクトに "External ID Field" として定義されている必要があります。対応する入力データに NULL 値を持つことはできません。	"Upsert" の場合ははい
writeBatchSize	各バッチで Salesforce に書き込まれたデータの行数。この値を 10,000 から 200,000 に設定することをお勧めします。各バッチの行数が少なすぎると、コピーのパフォーマンスが低下します。各バッチの行数が多すぎると、API のタイムアウトが発生する可能性があります。	いいえ (既定値は 100,000)
ignoreNullValues	書き込み操作時に入力データからの NULL 値を無視するかどうかを示します。使用可能な値: true および false。 - True:upsert または更新操作を行うときに、対象オブジェクト内のデータが変更されないようにします。挿入操作を実行するときに、定義済みの既定値を挿入します。 - False:upsert または更新操作を行うときに、対象オブジェクト内のデータを NULL に更新します。挿入操作を実行するときに、NULL 値を挿入します。	いいえ (既定値は false)
maxConcurrentConnections	アクティビティの実行中にデータストアに対して確立されたコンカレント接続数の上限。コンカレント接続を制限する場合にのみ、値を指定します。	なし

例:コピーアクティビティでの Salesforce シンク

"activities":[
    {
        "name": "CopyToSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Salesforce output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "SalesforceV2Sink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

Salesforce のデータ型マッピング

Salesforce からデータをコピーするときに、次のマッピングが Salesforce のデータ型からそのサービス内の中間データ型に内部的に使用されます。コピーアクティビティでソースのスキーマとデータ型がシンクにマッピングされるしくみについては、スキーマとデータ型のマッピングに関する記事を参照してください。

Salesforce のデータ型	サービスの中間データ型
Auto Number	String
Checkbox	Boolean
Currency	Decimal
Date	DateTime
日付/時刻	DateTime
メール	String
id	String
Lookup Relationship	String
Multi-Select Picklist	String
Number	Decimal
Percent	Decimal
Phone	String
Picklist	String
テキスト	String
Text Area	String
Text Area (Long)	String
Text Area (Rich)	String
Text (Encrypted)	String
URL	String

注意

Salesforce Number 型は、サービスの中間データ型として、Azure Data Factory および Azure Synapse パイプラインの Decimal 型にマッピングされています。 Decimal 型では、定義された有効桁数と小数点以下桁数が適用されます。 小数点以下の桁数が定義された小数点以下桁数を超えるデータの場合、その値はプレビューデータで端数が丸められ、コピーされます。 Azure Data Factory および Azure Synapse パイプラインでこのような有効桁数の損失が発生しないようにするには、Salesforce の [Custom Field Definition Edit](カスタムフィールド定義の編集) ページで小数点以下の桁数をかなり大きな値に設定することを検討してください。

Lookup アクティビティのプロパティ

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。

Salesforce のリンクサービスをアップグレードする

リンクサービスと関連するクエリをアップグレードするのに役立つ手順を次に示します。

「前提条件」を参照して、Salesforce ポータルで接続アプリを構成します。
新しい Salesforce リンクサービスを作成し、「リンクされたサービスのプロパティ」を参照して構成します。
レガシリンクサービスを参照するコピーアクティビティのソースまたは検索アクティビティで SQL クエリを使用する場合は、それらを SOQL クエリに変換する必要があります。 SOQL クエリの詳細については、「ソースタイプとしての Salesforce」と「Salesforce オブジェクトクエリ言語 (SOQL)」を参照してください。
readBehavior は、copy アクティビティのソースまたは lookup アクティビティの includeDeletedObjects に置き換えられます。詳細な構成については、「ソースの種類としての Salesforce」を参照してください。

Salesforce と Salesforce (レガシ) の違い

Salesforce コネクタでは新しい機能を提供し、Salesforce (レガシ) コネクタのほとんどの機能と互換性があります。次の表では、Salesforce と Salesforce (レガシ) の機能の違いを示しています。

セールスフォース	Salesforce (レガシ)
Salesforce Bulk API 2.0 内で SOQL をサポートします。 SOQL クエリの場合: • GROUP BY、LIMIT、ORDER BY、OFFSET、または TYPEOF 句はサポートされていません。 • COUNT() などの集計関数はサポートされていません。Salesforce レポートを使用してそれらを実装できます。 • GROUP BY 句の日付関数はサポートされていませんが、WHERE 句でサポートされます。 • 複合住所フィールドまたは複合位置情報フィールドはサポートされていません。別の方法として、複合フィールドの個々のコンポーネントに対してクエリを実行します。 • 親-子リレーションシップクエリはサポートされていませんが、子-親リレーションシップクエリはサポートされています。	SQL 構文と SOQL 構文の両方をサポートします。
バイナリフィールドを含むオブジェクトはサポートされていません。	Attachment オブジェクトのように、バイナリフィールドを含むオブジェクトがサポートされています。
Bulk API 内のオブジェクトをサポートします。詳細については、こちらの記事をご覧ください。	CaseStatus など、Bulk API でサポートされていないオブジェクトをサポートします。
レポート ID を選択してレポートをサポートします。	`{call "<report name>"}` などのレポートクエリ構文をサポートします。

コピーアクティビティによってソース、シンクとしてサポートされるデータストアの一覧については、サポートされるデータストアに関するセクションを参照してください。