Verschieben von Daten aus Salesforce mithilfe von Azure Data Factory

Hinweis

Dieser Artikel gilt für Version 1 von Data Factory. Wenn Sie die aktuelle Version des Data Factory-Diensts verwenden, finden Sie weitere Informationen unter Salesforce-Connector in V2.

In diesem Artikel wird die Verwendung der Kopieraktivität in einer Azure Data Factory beschrieben, um Daten aus Salesforce in einen Datenspeicher zu kopieren, der in der Tabelle Unterstützte Quellen und Senken in der Spalte „Senke“ aufgeführt ist. Dieser Artikel baut auf dem Artikel Datenverschiebungsaktivitäten auf, der eine allgemeine Übersicht zur Datenverschiebung mit Kopieraktivität und unterstützten Datenspeicherkombinationen bietet.

Azure Data Factory unterstützt derzeit nur das Verschieben von Daten aus Salesforce in unterstützte Senkendatenspeicher, aber nicht das Verschieben von Daten aus anderen Datenspeichern nach Salesforce.

Unterstützte Versionen

Dieser Connector unterstützt die folgenden Editionen von Salesforce: Developer Edition, Professional Edition, Enterprise Edition oder Unlimited Edition. Außerdem unterstützt er Kopiervorgänge aus der Produktionsumgebung, der Sandbox und der benutzerdefinierten Domäne von Salesforce.

Voraussetzungen

  • API-Berechtigungen müssen aktiviert sein.
  • Um Daten aus Salesforce in lokale Datenspeicher zu kopieren, muss in Ihrer lokalen Umgebung mindestens das Datenverwaltungsgateway 2.0 installiert sein.

Anforderungslimits in Salesforce

Salesforce weist Grenzwerte sowohl für die Gesamtanzahl von API-Anforderungen als auch für die Anzahl gleichzeitiger API-Anforderungen auf. Beachten Sie folgende Punkte:

  • Wenn die Anzahl von gleichzeitigen Anforderungen das Limit überschreitet, setzt eine Drosselung ein, und es werden zufällig generierte Fehler angezeigt.
  • Wenn die Gesamtanzahl von Anforderungen das Limit überschreitet, wird das Salesforce-Konto 24 Stunden lang gesperrt.

In beiden Szenarien wird Ihnen möglicherweise auch der Fehler „REQUEST_LIMIT_EXCEEDED“ angezeigt. Weitere Informationen finden Sie im Abschnitt „API Request Limits“ (API-Anforderungslimits) im Artikel Salesforce Developer Limits (Salesforce-Entwicklerlimits).

Erste Schritte

Sie können eine Pipeline mit einer Kopieraktivität erstellen, die Daten mithilfe verschiedener Tools/APIs aus Salesforce verschiebt.

Am einfachsten erstellen Sie eine Pipeline mit dem Kopier-Assistenten. Siehe Tutorial: Erstellen einer Pipeline mit dem Kopier-Assistenten finden Sie eine kurze exemplarische Vorgehensweise zum Erstellen einer Pipeline mithilfe des Assistenten zum Kopieren von Daten.

Sie können auch die folgenden Tools zum Erstellen einer Pipeline verwenden: Visual Studio, Azure PowerShell, Azure Resource Manager-Vorlage, .NET-API und REST-API. Im Tutorial zur Kopieraktivität finden Sie detaillierte Anweisungen, wie Sie eine Pipeline mit einer Kopieraktivität erstellen können.

Unabhängig davon, ob Sie Tools oder APIs verwenden, führen Sie die folgenden Schritte aus, um eine Pipeline zu erstellen, die Daten aus einem Quelldatenspeicher in einen Senkendatenspeicher verschiebt:

  1. Erstellen verknüpfter Dienste zum Verknüpfen von Eingabe- und Ausgabedatenspeichern mit Ihrer Data Factory.
  2. Erstellen von Datasets zur Darstellung von Eingabe- und Ausgabedaten für den Kopiervorgang.
  3. Erstellen einer Pipeline mit einer Kopieraktivität, die ein Dataset als Eingabe und ein Dataset als Ausgabe akzeptiert.

Wenn Sie den Assistenten verwenden, werden automatisch JSON-Definitionen für diese Data Factory-Entitäten (verknüpfte Diensten, Datasets und die Pipeline) erstellt. Bei Verwendung von Tools und APIs (mit Ausnahme der .NET-API) definieren Sie diese Data Factory-Entitäten im JSON-Format. Ein Beispiel mit JSON-Definitionen für Data Factory-Entitäten, die zum Kopieren von Daten aus Salesforce verwendet werden, finden Sie im Abschnitt JSON-Beispiel: Kopieren von Daten aus Salesforce in ein Azure-Blob in diesem Artikel.

Die folgenden Abschnitte enthalten Details zu JSON-Eigenschaften, die zum Definieren von Data Factory-Entitäten speziell für Salesforce verwendet werden:

Eigenschaften des verknüpften Diensts

Die folgende Tabelle enthält Beschreibungen der JSON-Elemente, die für den verknüpften Salesforce-Dienst spezifisch sind.

Eigenschaft BESCHREIBUNG Erforderlich
type Die type-Eigenschaft muss auf Folgendes festgelegt werden: Salesforce. Ja
environmentUrl Geben Sie die URL der Salesforce-Instanz an.

- Der Standardwert ist „https://login.salesforce.com"“.
- Um Daten aus einer Sandbox zu kopieren, geben Sie „https://test.salesforce.com"“ an.
- Geben Sie zum Kopieren von Daten aus der benutzerdefinierten Domäne z.B. „https://[Domäne].my.salesforce.com“ an.
Nein
username Geben Sie einen Benutzernamen für das Benutzerkonto an. Ja
password Geben Sie ein Kennwort für das Benutzerkonto an. Ja
securityToken Geben Sie ein Sicherheitstoken für das Benutzerkonto an. Anweisungen zum Abrufen oder Zurücksetzen eines Sicherheitstokens finden Sie unter Zurücksetzen Ihres Sicherheitstokens . Allgemeine Informationen zu Sicherheitstoken finden Sie unter Security and the API(Sicherheit und die API). Ja

Dataset-Eigenschaften

Eine vollständige Liste mit den Abschnitten und Eigenschaften, die zum Definieren von Datasets zur Verfügung stehen, finden Sie im Artikel Erstellen von Datasets . Abschnitte wie „structure“, „availability“ und „policy“ des JSON-Codes eines Datasets sind bei allen Dataset-Typen (Azure SQL, Azure-Blob, Azure-Tabelle usw.) ähnlich.

Der Abschnitt typeProperties unterscheidet sich bei jedem Typ von Dataset und bietet Informationen zum Speicherort der Daten im Datenspeicher. Der Abschnitt „typeProperties“ für ein Dataset vom Typ RelationalTable hat die folgenden Eigenschaften:

Eigenschaft BESCHREIBUNG Erforderlich
tableName Name der Tabelle in Salesforce. Nein (wenn eine Abfrage von RelationalSource angegeben ist)

Wichtig

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

Screenshot shows the Custom Object Definition Detail where you can see the A P I names of the custom objects.

Eigenschaften der Kopieraktivität

Eine vollständige Liste mit den Abschnitten und Eigenschaften zum Definieren von Aktivitäten finden Sie im Artikel Erstellen von Pipelines . Eigenschaften wie Name, Beschreibung, Eingabe- und Ausgabetabellen und verschiedene Richtlinien sind für alle Arten von Aktivitäten verfügbar.

Die Eigenschaften im Abschnitt „typeProperties“ der Aktivität können dagegen je nach Aktivitätstyp variieren. Für die Kopieraktivität variieren die Eigenschaften je nach Art der Quellen und Senken.

Wenn die Quelle bei der Kopieraktivität den Typ RelationalSource aufweist (dies schließt Salesforce ein), sind im Abschnitt „typeProperties“ die folgenden Eigenschaften verfügbar:

Eigenschaft BESCHREIBUNG Zulässige Werte Erforderlich
Abfrage Verwendet die benutzerdefinierte Abfrage zum Lesen von Daten. Eine SQL-92-Abfrage oder eine Abfrage vom Typ Salesforce Object Query Language (SOQL). Beispiel: select * from MyTable__c. Nein (wenn tableName von dataset angegeben ist)

Wichtig

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

Screenshot shows the Custom Fields & Relationships where you can see the A P I names of the custom objects.

Tipps zu Abfragen

Abrufen von Daten mithilfe der WHERE-Klausel für die DateTime-Spalte

Achten Sie beim Angeben der SOQL- oder SQL-Abfrage auf den Unterschied beim DateTime-Format. Beispiel:

  • SOQL-Beispiel: $$Text.Format('SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= {0:yyyy-MM-ddTHH:mm:ssZ} AND LastModifiedDate < {1:yyyy-MM-ddTHH:mm:ssZ}', WindowStart, WindowEnd)
  • SQL-Beispiel:
    • Verwenden des Assistenten zum Kopieren, um die Abfrage anzugeben:$$Text.Format('SELECT * FROM Account WHERE LastModifiedDate >= {{ts\'{0:yyyy-MM-dd HH:mm:ss}\'}} AND LastModifiedDate < {{ts\'{1:yyyy-MM-dd HH:mm:ss}\'}}', WindowStart, WindowEnd)
    • Verwenden der JSON-Bearbeitung, um die Abfrage anzugeben („char“ muss ordnungsgemäß mit Escapezeichen versehen werden):$$Text.Format('SELECT * FROM Account WHERE LastModifiedDate >= {{ts\\'{0:yyyy-MM-dd HH:mm:ss}\\'}} AND LastModifiedDate < {{ts\\'{1:yyyy-MM-dd HH:mm:ss}\\'}}', WindowStart, WindowEnd)

Abrufen von Daten aus Salesforce-Bericht

Sie können Daten aus Salesforce-Berichten abrufen, indem Sie z.B. die Abfrage {call "<report name>"} angeben. "query": "{call \"TestReport\"}".

Abrufen von gelöschten Datensätzen aus dem Salesforce-Papierkorb

Zum Abfragen der vorläufig gelöschten Datensätze aus dem Salesforce-Papierkorb können Sie in der Abfrage „IsDeleted = 1“ angeben. Beispiel:

  • Zum Abfragen lediglich der gelöschten Datensätze geben Sie „select * from MyTable__c where IsDeleted= 1“ an.
  • Zum Abfragen aller Datensätze, d.h. der vorhandenen und der gelöschten Datensätze, geben Sie „select * from MyTable__c where IsDeleted = 0 or IsDeleted = 1“ an.

JSON-Beispiel: Kopieren von Daten aus Salesforce in ein Azure-Blob

Das folgende Beispiel zeigt JSON-Beispieldefinitionen, die Sie zum Erstellen einer Pipeline mit Visual Studio oder Azure PowerShell verwenden können. Darin wird veranschaulicht, wie Sie Daten aus Salesforce in Azure Blob Storage kopieren. Daten können jedoch auch mithilfe der Kopieraktivität in Azure Data Factory in eine beliebige der hier aufgeführten Senken kopiert werden.

Hier sind die Data Factory-Artefakte angegeben, die Sie zum Implementieren des Szenarios erstellen müssen. Die darauffolgenden Abschnitte enthalten die Details zu diesen Schritten.

Verknüpfter Salesforce-Dienst

In diesem Beispiel wird der verknüpfte Dienst Salesforce verwendet. Im Abschnitt Verknüpfter Salesforce-Dienst finden Sie die Eigenschaften, die von diesem verknüpften Dienst unterstützt werden. Eine Anleitung zum Zurücksetzen oder Abrufen des Sicherheitstokens finden Sie unter Zurücksetzen Ihres Sicherheitstokens .

{
    "name": "SalesforceLinkedService",
    "properties":
    {
        "type": "Salesforce",
        "typeProperties":
        {
            "username": "<user name>",
            "password": "<password>",
            "securityToken": "<security token>"
        }
    }
}

Mit Azure Storage verknüpfter Dienst

{
    "name": "AzureStorageLinkedService",
    "properties": {
        "type": "AzureStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
        }
    }
}

Salesforce-Eingabedataset:

{
    "name": "SalesforceInput",
    "properties": {
        "linkedServiceName": "SalesforceLinkedService",
        "type": "RelationalTable",
        "typeProperties": {
            "tableName": "AllDataType__c"
        },
        "availability": {
            "frequency": "Hour",
            "interval": 1
        },
        "external": true,
        "policy": {
            "externalData": {
                "retryInterval": "00:01:00",
                "retryTimeout": "00:10:00",
                "maximumRetry": 3
            }
        }
    }
}

Durch Festlegen von external auf true wird dem Data Factory-Dienst mitgeteilt, dass das Dataset für die Data Factory extern ist und nicht durch eine Aktivität in der Data Factory erzeugt wird.

Wichtig

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

Screenshot shows the Custom Object Definition Detail where you can see Singular Label, Plural Label, Object Name, and A P I Name.

Azure-Blob-Ausgabedataset

Daten werden stündlich in ein neues Blob geschrieben (frequency: hour, interval: 1).

{
    "name": "AzureBlobOutput",
    "properties":
    {
        "type": "AzureBlob",
        "linkedServiceName": "AzureStorageLinkedService",
        "typeProperties":
        {
            "folderPath": "adfgetstarted/alltypes_c"
        },
        "availability":
        {
            "frequency": "Hour",
            "interval": 1
        }
    }
}

Pipeline mit Kopieraktivität

Die Pipeline enthält eine Kopieraktivität, die für das Verwenden der Ein- und Ausgabedatasets und für eine stündliche Ausführung konfiguriert ist. In der JSON-Definition der Pipeline ist der Typ source auf RelationalSource und der Typ sink auf BlobSink festgelegt.

Unter RelationalSource-Typeigenschaften finden Sie die Liste mit den Eigenschaften, die von RelationalSource unterstützt werden.

{
    "name":"SamplePipeline",
    "properties":{
        "start":"2016-06-01T18:00:00",
        "end":"2016-06-01T19:00:00",
        "description":"pipeline with copy activity",
        "activities":[
        {
            "name": "SalesforceToAzureBlob",
            "description": "Copy from Salesforce to an Azure blob",
            "type": "Copy",
            "inputs": [
            {
                "name": "SalesforceInput"
            }
            ],
            "outputs": [
            {
                "name": "AzureBlobOutput"
            }
            ],
            "typeProperties": {
                "source": {
                    "type": "RelationalSource",
                    "query": "SELECT Id, Col_AutoNumber__c, Col_Checkbox__c, Col_Currency__c, Col_Date__c, Col_DateTime__c, Col_Email__c, Col_Number__c, Col_Percent__c, Col_Phone__c, Col_Picklist__c, Col_Picklist_MultiSelect__c, Col_Text__c, Col_Text_Area__c, Col_Text_AreaLong__c, Col_Text_AreaRich__c, Col_URL__c, Col_Text_Encrypt__c, Col_Lookup__c FROM AllDataType__c"
                },
                "sink": {
                    "type": "BlobSink"
                }
            },
            "scheduler": {
                "frequency": "Hour",
                "interval": 1
            },
            "policy": {
                "concurrency": 1,
                "executionPriorityOrder": "OldestFirst",
                "retry": 0,
                "timeout": "01:00:00"
            }
        }
        ]
    }
}

Wichtig

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

Screenshot shows the Custom Fields & Relationships with the A P I names called out.

Typzuordnung für Salesforce

Salesforce-Typ .NET-basierter Typ
Auto Number String
Checkbox Boolean
Währung Decimal
Date Datetime
Date/Time Datetime
Email 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

Weitere Informationen zum Zuordnen von Spalten im Quelldataset zu Spalten im Senkendataset finden Sie unter Zuordnen von Datasetspalten in Azure Data Factory.

Angeben der Strukturdefinition für rechteckige Datasets

Der Abschnitt „structure“ in der JSON von Datasets ist ein optionaler Abschnitt für rechteckige Tabellen (mit Zeilen und Spalten) und enthält eine Auflistung der Spalten der Tabelle. Sie verwenden den Abschnitt "structure" entweder zum Angeben von Typinformationen für Typumwandlungen oder für Spaltenzuordnungen. In den folgenden Abschnitten werden diese Features ausführlich beschrieben.

Jede Spalte enthält die folgenden Eigenschaften:

Eigenschaft BESCHREIBUNG Erforderlich
name Name der Spalte. Ja
type Datentyp der Spalte. Im nachstehenden Abschnitt "Typkonvertierungen" finden Sie Details zur Angabe von Typinformationen. Nein
culture Zu verwendendes .NET-basiertes Gebietsschema, wenn "type" angegeben ist und den .NET-Typ "Datetime" oder "Datetimeoffset" hat. Die Standardeinstellung ist "en-us". Nein
format Zu verwendende Formatzeichenfolge, wenn "type" angegeben ist und den .NET-Typ "Datetime" oder "Datetimeoffset" hat. Nein

Das folgende Beispiel zeigt den Abschnitt "structure" der JSON für eine Tabelle mit den drei Spalten "userid", "name" und "lastlogindate".

"structure": 
[
    { "name": "userid"},
    { "name": "name"},
    { "name": "lastlogindate"}
],

Befolgen Sie die folgenden Angaben dazu, wann der Abschnitt structure mit welchen Informationen verwendet werden sollte.

  • Für strukturierte Datenquellen, die Datenschema- und Typinformationen neben den Daten selbst speichern (wie etwa SQL Server, Oracle, Azure-Tabelle usw.), sollten Sie den Abschnitt „structure“ nur angeben, wenn bestimmte Quellspalten bestimmten Zielspalten in der Senke zugewiesen werden sollen und deren Namen nicht identisch sind (Einzelheiten finden Sie im nachfolgenden Abschnitt zur Spaltenzuordnung).

    Wie bereits erwähnt, ist die Information "type" im Abschnitt "structure" optional. Für strukturierte Datenquellen steht die Information "type" bereits als Teil der Datasetdefinition im Datenspeicher zur Verfügung, weshalb Sie Typinformationen nicht dem Abschnitt "structure" hinzufügen müssen.

  • Für das Schema von Lesedatenquellen (insbesondere Azure-Blob) können Sie Daten speichern, ohne Schema- oder Typinformationen mit den Daten zu speichern. Bei diesen Typen von Datenquellen sollten Sie den Abschnitt "structure" in den beiden folgenden Fällen hinzufügen:

    • Sie wünschen eine Spaltenzuordnung.
    • Wenn das Dataset eine Quelle in einer Kopieraktivität ist, können Sie Typinformationen in "structure" bereitstellen. Data Factory verwendet diese Typinformationen für die Konvertierung in systemeigene Typen für die Senke. Weitere Informationen finden Sie im Artikel Verschieben von Daten in einen und aus einem Azure-Blob.

Unterstützte .NET-basierte Typen

Data Factory unterstützt die folgenden CLS-konformen auf .NET basierenden Typwerte für die Bereitstellung von Typinformationen in "structure" für das Schema von Lesedatenquellen wie Azure-Blob.

  • Int16
  • Int32
  • Int64
  • Single
  • Double
  • Decimal
  • Byte[]
  • Bool
  • String
  • Guid
  • Datetime
  • Datetimeoffset
  • Timespan

Für „Datetime“ und „Datetimeoffset“ können Sie optional auch die Zeichenfolgen „culture“ und „format“ angeben, um das Analysieren Ihrer benutzerdefinierten „Datetime“-Zeichenfolge zu erleichtern. Nachstehend sehen Sie ein Beispiel einer Typumwandlung.

Leistung und Optimierung

Im Handbuch zur Leistung und Optimierung der Kopieraktivität werden wichtige Faktoren beschrieben, die sich auf die Leistung der Datenverschiebung (Kopieraktivität) in Azure Data Factory auswirken, sowie verschiedene Möglichkeiten zur Leistungsoptimierung.