Kopieren von Daten aus und nach Salesforce mit Azure Data Factory oder Azure Synapse Analytics

Artikel
04/21/2024

GILT FÜR: Azure Data Factory Azure Synapse Analytics

Tipp

Testen Sie Data Factory in Microsoft Fabric, eine All-in-One-Analyselösung für Unternehmen. Microsoft Fabric deckt alle Aufgaben ab, von der Datenverschiebung bis hin zu Data Science, Echtzeitanalysen, Business Intelligence und Berichterstellung. Erfahren Sie, wie Sie kostenlos eine neue Testversion starten!

In diesem Artikel wird beschrieben, wie Sie die Kopieraktivität in Azure Data Factory- und Azure Synapse-Pipelines verwenden, um Daten aus und in Salesforce zu kopieren. Er baut auf dem Artikel zur Übersicht über die Kopieraktivität auf, der eine allgemeine Übersicht über die Kopieraktivität enthält.

Wichtig

Der neue Salesforce-Connector bietet verbesserte native Salesforce-Unterstützung. Wenn Sie den älteren Salesforce-Connector in Ihrer Lösung verwenden, der lediglich aus Gründen der Abwärtskompatibilität unverändert unterstützt wird, finden Sie entsprechende Informationen im Artikel Salesforce-Connector (Legacy).

Unterstützte Funktionen

Der Salesforce-Connector wird für die folgenden Funktionen unterstützt:

Unterstützte Funktionen	IR
Kopieraktivität (Quelle/Senke)	① ②
Lookup-Aktivität	① ②

① Azure Integration Runtime ② Selbstgehostete Integration Runtime

Eine Liste der Datenspeicher, die als Quellen oder Senken unterstützt werden, finden Sie in der Tabelle der unterstützten Datenspeicher.

Dieser Salesforce-Connector unterstützt insbesondere Folgendes:

Salesforce Developer, Professional, Enterprise oder Unlimited Edition.
Kopieren von Daten aus und in eine benutzerdefinierte Domäne (eine benutzerdefinierte Domäne kann sowohl in Produktions- als auch in Sandboxumgebungen konfiguriert werden).

Sie können die zum Lesen/Schreiben von Daten verwendete API-Version explizit über die apiVersion-Eigenschaft im verknüpften Dienst festlegen. Beim Kopieren von Daten in Salesforce verwendet der Connector BULK API 2.0.

Voraussetzungen

API-Berechtigungen müssen in Salesforce aktiviert sein.
Sie müssen die Connected Apps im Salesforce-Portal konfigurieren, indem Sie sich auf dieses offizielle Dokument oder unsere Schritt-für-Schritt-Anleitung in der Empfehlung in diesem Artikel beziehen.
Wichtig
- Der oder die ausführende Benutzer*in benötigt die Berechtigung „API Only“.
- Die Ablaufzeit des Zugriffstokens kann über Sitzungsrichtlinien anstelle des Aktualisierungstokens geändert werden.

Grenzwerte der Salesforce-Bulk-API 2.0

Wir verwenden die Salesforce-Bulk-API 2.0 zum Abfragen und Erfassen von Daten. In der Bulk-API 2.0 werden Batches automatisch für Sie erstellt. Sie können bis zu 15.000 Batches pro rollierendem 24-Stunden-Zeitraum übermitteln. Wenn Batches den Grenzwert überschreiten, werden Fehler angezeigt.

In der Bulk-API 2.0 verbrauchen nur Erfassungsaufträge Batches, Abfrageaufträge jedoch nicht. Ausführliche Informationen finden Sie unter Verarbeiten von Anforderungen im Bulk-API 2.0-Entwicklerhandbuch.

Weitere Informationen finden Sie im Abschnitt „Allgemeine Grenzwerte“ im Dokument Salesforce-Entwicklergrenzwerte.

Erste Schritte

Sie können eines der folgenden Tools oder SDKs verwenden, um die Kopieraktivität mit einer Pipeline zu verwenden:

Erstellen eines verknüpften Diensts mit Salesforce über die Benutzeroberfläche

Verwenden Sie die folgenden Schritte, um einen verknüpften Dienst mit Salesforce auf der Azure-Portal Benutzeroberfläche zu erstellen.

Navigieren Sie in Ihrem Azure Data Factory- oder Synapse-Arbeitsbereich zu der Registerkarte „Verwalten“, wählen Sie „Verknüpfte Dienste“ aus und klicken Sie dann auf „Neu“:
- Azure Data Factory
- Azure Synapse
Suchen Sie nach Salesforce, und wählen Sie den Salesforce-Connector aus.
Konfigurieren Sie die Dienstdetails, testen Sie die Verbindung, und erstellen Sie den neuen verknüpften Dienst.

Details zur Connector-Konfiguration

Die folgenden Abschnitte enthalten Details zu Eigenschaften, die zum Definieren von Entitäten speziell für den Salesforce-Connector verwendet werden.

Eigenschaften des verknüpften Diensts

Folgende Eigenschaften werden für den mit Salesforce verknüpften Dienst unterstützt:

Eigenschaft	Beschreibung	Erforderlich
Typ	Die type-Eigenschaft muss auf SalesforceV2 festgelegt sein.	Ja
environmentUrl	Geben Sie die URL der Salesforce-Instanz an. Geben Sie z. B. `"https://<domainName>.my.salesforce.com"` an, um Daten aus der benutzerdefinierten Domäne zu kopieren. In diesem Artikel erfahren Sie, wie Sie Ihre benutzerdefinierte Domäne konfigurieren oder anzeigen.	Ja
authenticationType	Typ der Authentifizierung für die Verbindung mit Salesforce. Der zulässige Wert ist OAuth2ClientCredentials.	Ja
clientId	Geben Sie die Client-ID der verbundenen Salesforce OAuth 2.0-App an. Weitere Informationen finden Sie in diesem Artikel.	Ja
clientSecret	Geben Sie den geheimen Clientschlüssel der verbundenen Salesforce OAuth 2.0-App an. Weitere Informationen finden Sie in diesem Artikel.	Ja
apiVersion	Geben Sie die zu verwendende Salesforce Bulk API 2.0-Version an, z. B. `52.0`. Die Bulk-API 2.0 unterstützt nur API-Versionen >= 47.0. Weitere Informationen zur Bulk API 2.0 finden Sie in diesem Artikel. Wenn Sie eine niedrigere API-Version verwenden, führt dies zu einem Fehler.	Ja
connectVia	Die Integration Runtime, die zum Herstellen einer Verbindung mit dem Datenspeicher verwendet werden soll. Wenn keine Option angegeben ist, wird die standardmäßige Azure Integration Runtime verwendet.	Nein

Beispiel: Speichern von Anmeldeinformationen

{
    "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"
        }
    }
}

Beispiel: Speichern von Anmeldeinformationen in 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"
        }
    }
}

Beispiel: Speichern von Anmeldeinformationen sowie environmentUrl und clientId in Key Vault

Beachten Sie, dass Sie dadurch nicht mehr in der Lage sind, Einstellungen über die Benutzeroberfläche zu bearbeiten. Das Kontrollkästchen Dynamische Inhalte im JSON-Format angeben wird aktiviert, und Sie müssen diese Konfiguration vollständig manuell bearbeiten. Der Vorteil ist, dass Sie ALLE Konfigurationseinstellungen aus Key Vault ableiten können, statt an dieser Stelle Parameter hinzuzufügen.

{
    "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"
        }
    }
}

Dataset-Eigenschaften

Eine vollständige Liste mit den Abschnitten und Eigenschaften, die zum Definieren von Datasets zur Verfügung stehen, finden Sie im Artikel zu Datasets. Dieser Abschnitt enthält eine Liste der Eigenschaften, die vom Salesforce-Dataset unterstützt werden.

Legen Sie zum Kopieren von Daten aus und nach Salesforce die type-Eigenschaft des Datasets auf SalesforceV2Object fest. Die folgenden Eigenschaften werden unterstützt.

Eigenschaft	Beschreibung	Erforderlich
Typ	Die type-Eigenschaft muss auf SalesforceV2Object festgelegt sein.	Ja
objectApiName	Der Name des Salesforce-Objekts, aus dem Daten abgerufen werden sollen.	Nein: Quelle (wenn „SOQLQuery“ in der Quelle angegeben ist), Ja: Senke
reportId	Die ID des Salesforce-Berichts, aus dem Daten abgerufen werden sollen. Diese wird in der Senke nicht unterstützt. Beachten Sie, dass das Verwenden von Berichten Einschränkungen unterliegt.	Nein: Quelle (wenn „SOQLQuery“ in der Quelle angegeben ist), Senke wird nicht unterstützt

Wichtig

Der Teil „__c“ von API Name wird für benutzerdefinierte Objekte benötigt.

der API-Name für die Salesforce-Verbindung

Beispiel:

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

Eigenschaften der Kopieraktivität

Eine vollständige Liste mit den Abschnitten und Eigenschaften zum Definieren von Aktivitäten finden Sie im Artikel Pipelines. Dieser Abschnitt enthält eine Liste der Eigenschaften, die von der Salesforce-Quelle und -Senke unterstützt werden.

Salesforce als Quelltyp

Legen Sie zum Kopieren von Daten aus Salesforce den Quelltyp in der Kopieraktivität auf SalesforceV2Source fest. Die folgenden Eigenschaften werden im Abschnitt source der Kopieraktivität unterstützt.

Eigenschaft	Beschreibung	Erforderlich
Typ	Die type-Eigenschaft der Quelle der Kopieraktivität muss auf SalesforceV2Source festgelegt werden.	Ja
SOQLQuery	Verwendet die benutzerdefinierte Abfrage zum Lesen von Daten. Sie können SOQL-Abfragen (Salesforce Object Query Language) nur mit Einschränkungen verwenden. Informationen zu den SOQL-Einschränkungen finden Sie in diesem Artikel. Wenn die Abfrage nicht angegeben ist, werden alle Daten des Salesforce-Objekts abgerufen, das im Dataset unter „ObjectApiName/reportId“ angegeben ist.	Nein (wenn „ObjectApiName/reportId“ im Dataset angegeben ist)
includeDeletedObjects	Gibt an, ob die vorhandenen Datensätze oder alle Datensätze (einschließlich gelöschter Datensätze) abgefragt werden sollen. Wenn nicht angegeben, lautet das Standardverhalten „false“. Zulässige Werte sind false (Standard) und true.	No

Wichtig

Der Teil „__c“ von API Name wird für benutzerdefinierte Objekte benötigt.

Eine Liste der API-Namen für die Salesforce-Verbindung

Beispiel:

"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 als Senkentyp

Legen Sie zum Kopieren von Daten nach Salesforce den Senkentyp in der Kopieraktivität auf SalesforceV2Sink fest. Die folgenden Eigenschaften werden im Abschnitt sink der Kopieraktivität unterstützt.

Eigenschaft	Beschreibung	Erforderlich
Typ	Die type-Eigenschaft der Senke der Kopieraktivität muss auf SalesforceV2Sink festgelegt werden.	Ja
writeBehavior	Das Schreibverhalten für den Vorgang. Zulässige Werte: Insert und Upsert.	Nein (Standardwert ist „Insert“)
externalIdFieldName	Der Name des externen ID-Felds für den upsert-Vorgang. Das angegebene Feld muss als „Externes ID-Feld“ im Salesforce-Objekt definiert werden. Es kann keine NULL-Werte in den entsprechenden Eingabedaten haben.	Ja für „Upsert“
writeBatchSize	Die Zeilenanzahl der Daten, die in jedem Batch in Salesforce geschrieben werden. Es wird empfohlen, einen Wert zwischen 10.000 und 200.000 festzulegen. Zu wenige Zeilen in jedem Batch beeinträchtigen die Kopierleistung. Zu viele Zeilen in jedem Batch können zu API-Timeouts führen.	Nein (Standardwert: 100.000)
ignoreNullValues	Gibt an, ob NULL-Werte aus Eingabedaten während eines Schreibvorgangs ignoriert werden sollen. Zulässige Werte sind true und false. - true: Daten im Zielobjekt bleiben unverändert, wenn Sie einen upsert- oder update-Vorgang ausführen. Fügt beim Ausführen eines insert-Vorgangs einen definierten Standardwert ein. - false: Daten im Zielobjekt werden auf NULL aktualisiert, wenn Sie einen upsert- oder update-Vorgang ausführen. Fügt beim Ausführen eines insert-Vorgangs einen NULL-Wert ein.	Nein (Standardwert ist „false“)
maxConcurrentConnections	Die Obergrenze gleichzeitiger Verbindungen mit dem Datenspeicher während der Aktivitätsausführung. Geben Sie diesen Wert nur an, wenn Sie die Anzahl der gleichzeitigen Verbindungen begrenzen möchten.	Ohne

Beispiel: Salesforce-Senke in einer Kopieraktivität

"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
            }
        }
    }
]

Datentypzuordnung für Salesforce

Beim Kopieren von Daten aus Salesforce werden die folgenden Zuordnungen von Salesforce-Datentypen zu Zwischendatentypen innerhalb des Diensts verwendet. Weitere Informationen dazu, wie die Kopieraktivität das Quellschema und den Datentyp zur Senke zuordnet, finden Sie unter Schema- und Datentypzuordnungen.

Salesforce-Datentyp	Zwischendatentyp des Diensts
Auto Number	String
Checkbox	Boolean
Währung	Decimal
Date	Datetime
Date/Time	Datetime
E‑Mail	String
id	String
Lookup Relationship	String
Multi-Select Picklist	String
Number	Decimal
Percent	Decimal
Phone	String
Picklist	String
Text	String
Text Area	String
Text Area (Long)	String
Text Area (Rich)	String
Text (Encrypted)	String
URL	String

Hinweis

Der Salesforce-Typ „Zahl“ entspricht dem Typ „Dezimal“ in den Azure Data Factory- und Azure Synapse-Pipelines als Zwischendatentyp eines Dienstes. Der Typ „Dezimal“ berücksichtigt die definierte Genauigkeit und Skalierung. Für Daten, deren Dezimalstellen die definierte Skalierung überschreiten, wird der Wert in Vorschaudaten und -kopien abgerundet. Um einen solchen Genauigkeitsverlust in Azure Data Factory und Azure Synapse Pipelines zu vermeiden, sollten Sie die Dezimalstellen auf der Seite Benutzerdefinierte Felddefinition bearbeiten von Salesforce auf einen vernünftig großen Wert erhöhen.

Eigenschaften der Lookup-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter Lookup-Aktivität.

Upgrade des verknüpften Salesforce-Diensts

Die folgenden Schritte unterstützen Sie beim Upgrade Ihres verknüpften Diensts und der zugehörigen Abfragen:

Konfigurieren Sie die verbundenen Apps im Salesforce-Portal wie unter Voraussetzungen beschrieben.
Erstellen Sie einen neuen verknüpften Salesforce-Dienst, und konfigurieren Sie ihn wie unter Eigenschaften des verknüpften Diensts beschrieben.
Wenn Sie eine SQL-Abfrage in der Quelle der Kopieraktivität oder der Lookupaktivität verwenden, die sich auf den verknüpften Legacydienst bezieht, müssen Sie sie in eine SOQL-Abfrage konvertieren. Weitere Informationen zu SOQL-Abfragen finden Sie unter Salesforce als Quelltyp und Salesforce Object Query Language (SOQL).
readBehavior wird durch includeDeletedObjects in der Kopier- oder Lookup-Aktivität ersetzt. Die detaillierte Konfiguration finden Sie unter Salesforce als Quelltyp.

Unterschiede zwischen Salesforce und Salesforce (Legacy)

Der Salesforce-Connector bietet neue Funktionen und ist mit den meisten Features des Salesforce-Connectors (Legacy) kompatibel. Die folgende Tabelle zeigt die Funktionsunterschiede zwischen Salesforce und Salesforce (Legacy).

Salesforce	Salesforce (Legacy)
Unterstützen SOQL in Salesforce Bulk API 2.0. Für SOQL-Abfragen: • Die Klauseln GROUP BY, LIMIT, ORDER BY, OFFSET oder TYPEOF werden nicht unterstützt. • Aggregatfunktionen wie COUNT() werden nicht unterstützt. Sie können Salesforce-Berichte verwenden, um sie zu implementieren. • Datumsfunktionen in GROUP BY-Klauseln werden nicht unterstützt, aber in der WHERE-Klausel. • Zusammengesetzte Adressfelder oder zusammengesetzte Geolocation-Felder werden nicht unterstützt. Alternativ können Sie die einzelnen Komponenten zusammengesetzter Felder abfragen. • Abfragen zur Beziehung von übergeordneten zu untergeordneten Elementen werden nicht unterstützt, jedoch Abfragen zur Beziehung von untergeordneten zu übergeordneten Elementen.	Unterstützen sowohl die SQL- als auch die SOQL-Syntax.
Objekte, die binäre Felder enthalten, werden nicht unterstützt.	Objekte, die binäre Felder enthalten, werden unterstützt, z. B. das Attachment-Objekt.
Unterstützen Objekte innerhalb der Massen-API. hier finden Sie weitere Informationen	Unterstützen Objekte, die von der Massen-API nicht unterstützt werden, z. B. CaseStatus.
Unterstützen Berichte durch Auswählen einer Berichts-ID.	Unterstützen die Abfragesyntax des Berichts, z. B. `{call "<report name>"}`.

Eine Liste der Datenspeicher, die als Quelles und Senken für die Kopieraktivität unterstützt werden, finden Sie in Unterstützte Datenspeicher.

Kopieren von Daten aus und nach Salesforce mit Azure Data Factory oder Azure Synapse Analytics

Unterstützte Funktionen

Voraussetzungen

Grenzwerte der Salesforce-Bulk-API 2.0

Erste Schritte

Erstellen eines verknüpften Diensts mit Salesforce über die Benutzeroberfläche

Details zur Connector-Konfiguration

Eigenschaften des verknüpften Diensts

Dataset-Eigenschaften

Eigenschaften der Kopieraktivität

Salesforce als Quelltyp

Salesforce als Senkentyp

Datentypzuordnung für Salesforce

Eigenschaften der Lookup-Aktivität

Upgrade des verknüpften Salesforce-Diensts

Unterschiede zwischen Salesforce und Salesforce (Legacy)

Zugehöriger Inhalt

Zusätzliche Ressourcen