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

[アーティクル]
01/29/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

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

重要

サービスでは、Salesforce をネイティブでより適切にサポートする新しい Salesforce コネクタがリリースされました。詳細については、Salesforce コネクタに関する記事を参照してください。

サポートされる機能

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

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

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

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

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

Salesforce Developer、Professional、Enterprise、または Unlimited エディション。
Salesforce 運用環境、サンドボックス、およびカスタムドメインをコピー先またはコピー元とするデータのコピー。

注意

この関数は、上記の Salesforce 環境 (非営利団体サクセスパック (NPSP) を含む) からのスキーマのコピーをサポートします。

Salesforce コネクタは、Salesforce REST/Bulk API 上に構築されます。コネクタは、Salesforce からデータをコピーするときに、データサイズに基づいて REST または Bulk API を自動的に選択します。結果セットが大きい場合は、パフォーマンス向上のために Bulk API が使用されます。リンクされたサービス内で apiVersion プロパティを介してデータを読み書きするために使用する API のバージョンを明示的に設定できます。データの Salesforce へのコピー時に、コネクタでは BULK API v1 が使用されます。

注意

コネクタでは、Salesforce API の既定のバージョンが設定されなくなりました。後方互換性のために、既定の API バージョンが前に設定された場合、そのバージョンは動作し続けます。既定値はソースの場合は 45.0 で、シンクの場合は 40.0 です。

前提条件

Salesforce で API アクセス許可を有効にする必要があります。

Salesforce の要求の制限

Salesforce では、API 要求数の合計と、API の同時要求数に上限が設けられています。以下の点に注意してください。

同時要求数が上限を超えると調整が発生し、ランダムにエラーが表示されます。
要求数の合計が上限を超えると、Salesforce アカウントが 24 時間ブロックされます。

また、どちらのシナリオでも、"REQUEST_LIMIT_EXCEEDED" エラーメッセージが表示されることがあります。詳細については、Salesforce Developer の制限に関する資料の「API Request Limits」(API 要求の制限) をご覧ください。

はじめに

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

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

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

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

コネクタの構成の詳細

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

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

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

プロパティ	内容	必須
type	type プロパティを Salesforce に設定する必要があります。	はい
environmentUrl	Salesforce インスタンスの URL を指定します。既定値は `"https://login.salesforce.com"` です。 - サンドボックスからデータをコピーするには、`"https://test.salesforce.com"` を指定します。 - カスタムドメインからデータをコピーするには、`"https://[domain].my.salesforce.com"`のように指定します。	いいえ
username	ユーザーアカウントのユーザー名を指定します。	はい
password	ユーザーアカウントのパスワードを指定します。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	はい
securityToken	ユーザーアカウントのセキュリティトークンを指定します。セキュリティトークンの概要については、「Security and the API (セキュリティと API)」をご覧ください。セキュリティトークンをスキップできるのは、Salesforce で信頼済み IP アドレスの一覧に Integration Runtime の IP を追加した場合のみです。 Azure IR を使用する場合は、「Azure Integration Runtime の IP アドレス」を参照してください。セキュリティトークンの取得およびリセット方法については、セキュリティトークンの取得に関する記事を参照してください。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	いいえ
apiVersion	`52.0` など、使用する Salesforce の REST または Bulk API バージョンを指定します。	いいえ
connectVia	データストアに接続するために使用される統合ランタイム。指定されていない場合は、既定の Azure 統合ランタイムが使用されます。	いいえ

例: 資格情報を格納する

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "securityToken": {
                "type": "SecureString",
                "value": "<security token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例: environmentUrl とユーザー名だけでなく資格情報を Key Vault に格納する

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

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "username": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of username in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

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

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

プロパティ	内容	必須
type	type プロパティは SalesforceObject に設定する必要があります。	はい
objectApiName	データの取得元の Salesforce オブジェクト名。	ソースの場合はいいえ、シンクの場合ははい

重要

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

Screenshot showing Salesforce connection API Name.

例:

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

注意

旧バージョンとの互換性の維持:Salesforce からデータをコピーする際に、以前の "RelationalTable" 型のデータセットを引き続き使用できますが、新しい "SalesforceObject" 型に切り替えることを推奨するメッセージが表示されます。

プロパティ	内容	必須
type	データセットの type プロパティは RelationalTable に設定する必要があります。	はい
tableName	Salesforce のテーブル名。	いいえ (アクティビティソースの "query" が指定されている場合)

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

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

ソースタイプとしての Salesforce

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

プロパティ	内容	必須
type	コピーアクティビティのソースの type プロパティは SalesforceSource に設定する必要があります。	はい
query	カスタムクエリを使用してデータを読み取ります。 Salesforce オブジェクトクエリ言語 (SOQL) クエリまたは SQL-92 クエリを使用できます。その他のヒントについては、「クエリのヒント」セクションをご覧ください。クエリが指定されていない場合は、データセット内の "objectApiName"で指定された Salesforce オブジェクトのすべてのデータが取得されます。	いいえ (データセットの "objectApiName" が指定されている場合)
readBehavior	既存のレコード、または削除されたものを含むすべてのレコードの、どちらのクエリを行うかを示します。指定しない場合の既定の動作は前者です。使用可能な値: query (既定値)、queryAll.	いいえ

重要

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

Screenshot showing Salesforce connection API Name list.

例:

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

注意

旧バージョンとの互換性の維持:Salesforce からデータをコピーする際に、以前の "RelationalSource" 型のコピーを引き続き使用できますが、新しい "SalesforceSource" 型に切り替えることを推奨するメッセージが表示されます。

Note

Salesforce ソースでは、セルフホステッド統合ランタイムのプロキシ設定はサポートされていませんが、シンクではサポートされます。

シンクの種類としての Salesforce

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

プロパティ	内容	必須
type	コピーアクティビティのシンクの type プロパティは SalesforceSink に設定する必要があります。	はい
writeBehavior	操作の書き込み動作。使用可能な値: Insert および Upsert。	いいえ (既定値は Insert)
externalIdFieldName	Upsert 操作の外部 ID フィールドの名前。指定するフィールドは、Salesforce オブジェクトに "External ID Field" として定義されている必要があります。対応する入力データに NULL 値を持つことはできません。	"Upsert" の場合ははい
writeBatchSize	各バッチで Salesforce に書き込まれたデータの行数。	いいえ (既定値は 5,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": "SalesforceSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

クエリのヒント

Salesforce レポートからデータを取得する

クエリを {call "<report name>"} と指定することで、Salesforce レポートからデータを取得できます。たとえば "query": "{call \"TestReport\"}" です。

Salesforce のごみ箱から削除済みレコードを取得する

論理的に削除されたレコードを Salesforce のごみ箱から検索するには、readBehavior を queryAll と指定できます。

SOQL クエリと SQL クエリの構文の違い

Salesforce からデータをコピーするときは、SOQL クエリまたは SQL クエリのいずれかを使用できます。これら 2 つでは構文と機能のサポートが異なるので、混在させないように注意してください。 Salesforce でネイティブにサポートされている SOQL クエリを使用することをお勧めします。次の表に、主な違いを示します。

構文	SOQL モード	SQL モード
列の選択	コピーするフィールドをクエリで列挙する必要があります (例: `SELECT field1, filed2 FROM objectname`)	列の選択に加えて、`SELECT *` がサポートされています。
引用符	フィールド/オブジェクト名を引用符で囲むことはできません。	フィールド/オブジェクト名を引用符で囲むことができます (例: `SELECT "id" FROM "Account"`)
日時の形式	こちらの詳細と次のセクションのサンプルをご覧ください。	こちらの詳細と次のセクションのサンプルをご覧ください。
ブール値	`False` および `True` と表されます (例: `SELECT … WHERE IsDeleted=True`)。	0 または 1 と表されます (例: `SELECT … WHERE IsDeleted=1`)。
列の名前変更	サポートされていません。	サポートされています (例: `SELECT a AS b FROM …`)。
リレーションシップ	サポートされています (例: `Account_vod__r.nvs_Country__c`)。	サポートされていません。

DateTime 列で where 句を使用してデータを取得する

SOQL クエリまたは SQL クエリを指定する場合は、DateTime 形式の違いに注意してください。次に例を示します。

SOQL サンプル: SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= @{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-ddTHH:mm:ssZ')} AND LastModifiedDate < @{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-ddTHH:mm:ssZ')}
SQL の例: SELECT * FROM Account WHERE LastModifiedDate >= {ts'@{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-dd HH:mm:ss')}'} AND LastModifiedDate < {ts'@{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-dd HH:mm:ss')}'}

MALFORMED_QUERY:Truncated のエラー

"MALFORMED_QUERY:Truncated" のエラーが発生した場合、通常は、データ内に JunctionIdList 型の列があり、Salesforce において行数が多いデータなどのサポートに対して制限があることが原因です。移行するには、JunctionIdList 列の除外か、またはコピーする行数の制限を試みます (パーティション分割して複数のコピーアクティビティの実行にすることが可能です)。

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 アクティビティに関するページを参照してください。

次のステップ

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

Share via

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

サポートされる機能

前提条件

Salesforce の要求の制限

はじめに

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

コネクタの構成の詳細

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

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

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

ソースタイプとしての Salesforce

シンクの種類としての Salesforce

クエリのヒント

Salesforce レポートからデータを取得する

Salesforce のごみ箱から削除済みレコードを取得する

SOQL クエリと SQL クエリの構文の違い

DateTime 列で where 句を使用してデータを取得する

MALFORMED_QUERY:Truncated のエラー

Salesforce のデータ型マッピング

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

次のステップ

フィードバック

フィードバック

その他のリソース

Share via

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

サポートされる機能

前提条件

Salesforce の要求の制限

はじめに

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

コネクタの構成の詳細

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

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

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

ソース タイプとしての Salesforce

シンクの種類としての Salesforce

クエリのヒント

Salesforce レポートからデータを取得する

Salesforce のごみ箱から削除済みレコードを取得する

SOQL クエリと SQL クエリの構文の違い

DateTime 列で where 句を使用してデータを取得する

MALFORMED_QUERY:Truncated のエラー

Salesforce のデータ型マッピング

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

次のステップ

フィードバック

フィードバック

その他のリソース

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

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

ソースタイプとしての Salesforce