Teilen über

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

  • Artikel

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, aktualisieren Sie ihren Salesforce-Connector vor dem 11. Oktober 2024. Ausführliche Informationen zum Unterschied zwischen der Legacy- und der neuesten Version finden Sie in diesem Abschnitt .

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.

  1. 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“:

  2. Suchen Sie nach Salesforce, und wählen Sie den Salesforce-Connector aus.

    Screenshot: Salesforce-Connector

  3. Konfigurieren Sie die Dienstdetails, testen Sie die Verbindung, und erstellen Sie den neuen verknüpften Dienst.

    Ein Screenshot, der die Konfiguration des verknüpften Diensts für Salesforce zeigt.

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, tritt ein Fehler auf. 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

Durch das Speichern von Anmeldeinformationen sowie environmentUrl und clientId in Key Vault können Sie die Benutzeroberfläche zum Bearbeiten von Einstellungen länger verwenden. Das Kontrollkästchen Dynamische Inhalte im JSON-Format angeben muss aktiviert sein, und Sie müssen diese Konfiguration manuell bearbeiten. Der Vorteil dieses Szenarios 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. Die zutreffende Version der selbstgehosteten Integration Runtime ist mindestens 5.44.8984.1. Nein: Quelle (wenn „Abfrage“ in der Quelle angegeben ist), Ja: Senke
reportId Die ID des Salesforce-Berichts, aus dem Daten abgerufen werden sollen. Es wird in der Senke nicht unterstützt. Das Verwenden von Berichten unterliegt Einschränkungen. Die zutreffende Version der selbstgehosteten Integration Runtime ist mindestens 5.44.8984.1. Nein: Quelle (wenn „Abfrage“ 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
Abfrage 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 keine Abfrage angegeben ist, werden alle Daten des Salesforce-Objekts abgerufen, das in „objectApiName/reportId“ im Dataset 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",
                "query": "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:

  1. Konfigurieren Sie die verbundenen Apps im Salesforce-Portal wie unter Voraussetzungen beschrieben.

  2. Erstellen Sie einen neuen verknüpften Salesforce-Dienst, und konfigurieren Sie ihn wie unter Eigenschaften des verknüpften Diensts beschrieben. Sie müssen auch vorhandene Datasets, die auf dem alten verknüpften Dienst basieren, manuell aktualisieren und jedes Dataset bearbeiten, um stattdessen den neuen verknüpften Dienst zu verwenden.

  3. 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).

  4. 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-Connector (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 für Abfragen nicht unterstützt. Objekte, die binäre Felder enthalten, werden für Abfragen unterstützt.
Unterstützt für Abfragen Objekte in der Massen-API Unterstützt für Abfragen Objekte, die von der Massen-API nicht unterstützt werden
Unterstützen Berichte durch Auswählen einer Berichts-ID. Unterstützen die Abfragesyntax des Berichts, z. B. {call "<report name>"}.

Zugehöriger Inhalt

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