Gegevens kopiëren van en naar Salesforce met behulp van Azure Data Factory of Azure Synapse Analytics

VAN TOEPASSING OP: Azure Data Factory Azure Synapse Analytics

In dit artikel wordt beschreven hoe u kopieeractiviteit gebruikt in Azure Data Factory en Azure Synapse pijplijnen om gegevens van en naar Salesforce te kopiëren. Het is gebaseerd op het artikel Overzicht van kopieeractiviteit met een algemeen overzicht van de kopieeractiviteit.

Ondersteunde mogelijkheden

Deze Salesforce-connector wordt ondersteund voor de volgende mogelijkheden:

Ondersteunde mogelijkheden IR
Copy-activiteit (bron/sink) ① ②
Activiteit Lookup ① ②

(1) Azure Integration Runtime (2) Zelf-hostende Integration Runtime

Zie de tabel Ondersteunde gegevensarchieven voor een lijst met gegevensarchieven die worden ondersteund als bronnen of sinks.

Deze Salesforce-connector ondersteunt het volgende:

  • Salesforce Developer-, Professional-, Enterprise- of Unlimited-edities.
  • Gegevens kopiëren van en naar Salesforce-productie, sandbox en aangepast domein.

Notitie

Deze functie biedt ondersteuning voor het kopiëren van elk schema uit de hierboven genoemde Salesforce-omgevingen, waaronder het NpSP (Nonprofit Success Pack ).

De Salesforce-connector is gebouwd op basis van de Salesforce REST/Bulk-API. Bij het kopiëren van gegevens uit Salesforce kiest de connector automatisch tussen REST- en Bulk-API's op basis van de gegevensgrootte: wanneer de resultatenset groot is, wordt bulk-API gebruikt voor betere prestaties; U kunt de API-versie die wordt gebruikt voor het lezen/schrijven van gegevens expliciet instellen via apiVersion de eigenschap in de gekoppelde service. Bij het kopiëren van gegevens naar Salesforce gebruikt de connector BULK-API v1.

Notitie

De connector stelt de standaardversie voor Salesforce API niet meer in. Als er eerder een standaard-API-versie is ingesteld, blijft deze werken voor achterwaartse compatibiliteit. De standaardwaarde is 45.0 voor bron en 40.0 voor sink.

Vereisten

API-machtiging moet zijn ingeschakeld in Salesforce.

Limieten voor Salesforce-aanvragen

Salesforce heeft limieten voor zowel het totale aantal API-aanvragen als gelijktijdige API-aanvragen. Houd rekening met de volgende punten:

  • Als het aantal gelijktijdige aanvragen de limiet overschrijdt, treedt beperking op en ziet u willekeurige fouten.
  • Als het totale aantal aanvragen de limiet overschrijdt, wordt het Salesforce-account gedurende 24 uur geblokkeerd.

Mogelijk ontvangt u in beide scenario's ook het foutbericht 'REQUEST_LIMIT_EXCEEDED'. Zie de sectie API-aanvraaglimieten in Salesforce-ontwikkelaarslimieten voor meer informatie.

Aan de slag

Als u de kopieeractiviteit wilt uitvoeren met een pijplijn, kunt u een van de volgende hulpprogramma's of SDK's gebruiken:

Een gekoppelde service maken met Salesforce met behulp van de gebruikersinterface

Gebruik de volgende stappen om een gekoppelde service te maken met Salesforce in de gebruikersinterface van Azure Portal.

  1. Blader naar het tabblad Beheren in uw Azure Data Factory- of Synapse-werkruimte en selecteer Gekoppelde services en klik vervolgens op Nieuw:

  2. Zoek naar Salesforce en selecteer de Salesforce-connector.

    Schermopname van de Salesforce-connector.

  3. Configureer de servicedetails, test de verbinding en maak de nieuwe gekoppelde service.

    Schermopname van de configuratie van de gekoppelde service voor Salesforce.

Configuratiedetails van connector

In de volgende secties vindt u informatie over eigenschappen die worden gebruikt om entiteiten te definiëren die specifiek zijn voor de Salesforce-connector.

Gekoppelde service-eigenschappen

De volgende eigenschappen worden ondersteund voor de gekoppelde Salesforce-service.

Eigenschap Beschrijving Vereist
type De typeeigenschap moet worden ingesteld op Salesforce. Yes
environmentUrl Geef de URL van het Salesforce-exemplaar op.
- De standaardwaarde is "https://login.salesforce.com".
- Als u gegevens uit de sandbox wilt kopiëren, geeft u "https://test.salesforce.com"op.
- Als u gegevens wilt kopiëren uit een aangepast domein, geeft u bijvoorbeeld "https://[domain].my.salesforce.com"op.
No
gebruikersnaam Geef een gebruikersnaam op voor het gebruikersaccount. Yes
wachtwoord Geef een wachtwoord op voor het gebruikersaccount.

Markeer dit veld als securestring om het veilig op te slaan of verwijs naar een geheim dat is opgeslagen in Azure Key Vault.
Yes
securityToken Geef een beveiligingstoken op voor het gebruikersaccount.

Zie Beveiliging en de API voor meer informatie over beveiligingstokens in het algemeen. Het beveiligingstoken kan alleen worden overgeslagen als u het IP-adres van de Integration Runtime toevoegt aan de lijst met vertrouwde IP-adressen in Salesforce. Als u Azure IR gebruikt, raadpleegt u Azure Integration Runtime IP-adressen.

Zie Een beveiligingstoken ophalen en opnieuw instellen voor instructies over het ophalen en opnieuw instellen van een beveiligingstoken. Markeer dit veld als securestring om het veilig op te slaan of verwijs naar een geheim dat is opgeslagen in Azure Key Vault.
No
apiVersion Geef de salesforce REST/bulk-API-versie op die moet worden gebruikt, bijvoorbeeld 52.0. No
connectVia De integratieruntime die moet worden gebruikt om verbinding te maken met het gegevensarchief. Als dit niet is opgegeven, wordt de standaard Azure-Integration Runtime gebruikt. No

Voorbeeld: Referenties opslaan

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

Voorbeeld: Referenties opslaan in 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"
        }
    }
}

Eigenschappen van gegevensset

Zie het artikel Gegevenssets voor een volledige lijst met secties en eigenschappen die beschikbaar zijn voor het definiëren van gegevenssets . Deze sectie bevat een lijst met eigenschappen die worden ondersteund door de Salesforce-gegevensset.

Als u gegevens wilt kopiëren van en naar Salesforce, stelt u de typeeigenschap van de gegevensset in op SalesforceObject. De volgende eigenschappen worden ondersteund.

Eigenschap Beschrijving Vereist
type De typeeigenschap moet worden ingesteld op SalesforceObject. Yes
objectApiName De naam van het Salesforce-object waaruit gegevens moeten worden opgehaald. Nee voor bron, Ja voor sink

Belangrijk

Het onderdeel '__c' van DE API-naam is nodig voor elk aangepast object.

Naam van Salesforce-verbindings-API

Voorbeeld:

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

Notitie

Voor achterwaartse compatibiliteit: Wanneer u gegevens kopieert uit Salesforce, blijft het werken wanneer u de vorige gegevensset 'RelationalTable' gebruikt, terwijl u een suggestie ziet om over te schakelen naar het nieuwe type SalesforceObject.

Eigenschap Beschrijving Vereist
type De typeeigenschap van de gegevensset moet worden ingesteld op RelationalTable. Yes
tableName Naam van de tabel in Salesforce. Nee (als 'query' in de activiteitsbron is opgegeven)

Eigenschappen van de kopieeractiviteit

Zie het artikel Pijplijnen voor een volledige lijst met secties en eigenschappen die beschikbaar zijn voor het definiëren van activiteiten. Deze sectie bevat een lijst met eigenschappen die worden ondersteund door salesforce-bron en -sink.

Salesforce als brontype

Als u gegevens uit Salesforce wilt kopiëren, stelt u het brontype in de kopieeractiviteit in op SalesforceSource. De volgende eigenschappen worden ondersteund in de sectie Bron van kopieeractiviteit.

Eigenschap Beschrijving Vereist
type De typeeigenschap van de bron van de kopieeractiviteit moet worden ingesteld op SalesforceSource. Yes
query Gebruik de aangepaste query om gegevens te lezen. U kunt een SOQL-query (Salesforce Object Query Language) of SQL-92-query gebruiken. Zie meer tips in de sectie met querytips . Als de query niet is opgegeven, worden alle gegevens van het Salesforce-object dat is opgegeven in objectApiName in de gegevensset opgehaald. Nee (als objectApiName in de gegevensset is opgegeven)
readBehavior Hiermee wordt aangegeven of u een query wilt uitvoeren op de bestaande records of alle records wilt opvragen, inclusief de verwijderde records. Als dit niet is opgegeven, is het standaardgedrag het eerste.
Toegestane waarden: query (standaard), queryAll.
Nee

Belangrijk

Het onderdeel '__c' van DE API-naam is nodig voor elk aangepast object.

Lijst met naam van Salesforce-verbindings-API

Voorbeeld:

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

Notitie

Voor compatibiliteit met eerdere versies: Wanneer u gegevens kopieert vanuit Salesforce, blijft de bron werken als u de vorige typekopie RelationalSource gebruikt terwijl u een suggestie ziet om over te schakelen naar het nieuwe type SalesforceSource.

Notitie

Salesforce-bron biedt geen ondersteuning voor proxy-instellingen in de zelf-hostende Integration Runtime, maar sink wel.

Salesforce als sinktype

Als u gegevens wilt kopiëren naar Salesforce, stelt u het sinktype in de kopieeractiviteit in op SalesforceSink. De volgende eigenschappen worden ondersteund in de sectie sink voor kopieeractiviteiten.

Eigenschap Beschrijving Vereist
type De typeeigenschap van de sink van de kopieeractiviteit moet worden ingesteld op SalesforceSink. Yes
writeBehavior Het schrijfgedrag voor de bewerking.
Toegestane waarden zijn Invoegen en Upsert.
Nee (standaard is Invoegen)
externalIdFieldName De naam van het externe id-veld voor de upsert-bewerking. Het opgegeven veld moet worden gedefinieerd als 'Extern id-veld' in het Salesforce-object. Het kan geen NULL-waarden bevatten in de bijbehorende invoergegevens. Ja voor 'Upsert'
writeBatchSize Het aantal rijen met gegevens dat in elke batch naar Salesforce is geschreven. Nee (standaard is 5.000)
ignoreNullValues Hiermee wordt aangegeven of NULL-waarden van invoergegevens tijdens een schrijfbewerking moeten worden genegeerd.
Toegestane waarden zijn waar en onwaar.
- Waar: laat de gegevens in het doelobject ongewijzigd wanneer u een upsert- of updatebewerking uitvoert. Voeg een gedefinieerde standaardwaarde in wanneer u een invoegbewerking uitvoert.
- Onwaar: werk de gegevens in het doelobject bij naar NULL wanneer u een upsert- of updatebewerking uitvoert. Voeg een NULL-waarde in wanneer u een invoegbewerking uitvoert.
Nee (standaard is onwaar)
 maxConcurrentConnections De bovengrens van gelijktijdige verbindingen die tijdens de uitvoering van de activiteit tot stand zijn gebracht met het gegevensarchief. Geef alleen een waarde op als u gelijktijdige verbindingen wilt beperken.  No

Voorbeeld: Salesforce-sink in een kopieeractiviteit

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

Querytips

Gegevens ophalen uit een Salesforce-rapport

U kunt gegevens ophalen uit Salesforce-rapporten door een query op te geven als {call "<report name>"}. Een voorbeeld is "query": "{call \"TestReport\"}".

Verwijderde records ophalen uit de Prullenbak van Salesforce

Als u een query wilt uitvoeren op de voorlopig verwijderde records uit de Prullenbak van Salesforce, kunt u opgeven readBehavior als queryAll.

Verschil tussen SOQL en SQL-querysyntaxis

Wanneer u gegevens kopieert vanuit Salesforce, kunt u een SOQL-query of SQL-query gebruiken. Houd er rekening mee dat deze twee verschillende syntaxis- en functionaliteitsondersteuning hebben, niet combineren. U wordt aangeraden de SOQL-query te gebruiken, die systeemeigen wordt ondersteund door Salesforce. De volgende tabel bevat de belangrijkste verschillen:

Syntax SOQL-modus SQL-modus
Kolomselectie U moet de velden opsommen die moeten worden gekopieerd in de query, bijvoorbeeld SELECT field1, filed2 FROM objectname SELECT * wordt ondersteund naast kolomselectie.
Aanhalingstekens Namen van bestanden/objecten kunnen niet worden aangeroepen. Veld-/objectnamen kunnen worden aangeroepen, bijvoorbeeld SELECT "id" FROM "Account"
Datum/tijd-notatie Raadpleeg hier de details en voorbeelden in de volgende sectie. Raadpleeg hier de details en voorbeelden in de volgende sectie.
Booleaanse waarden Vertegenwoordigd als False en True, bijvoorbeeld SELECT … WHERE IsDeleted=True. Vertegenwoordigd als 0 of 1, bijvoorbeeld SELECT … WHERE IsDeleted=1.
Kolomnaam wijzigen Wordt niet ondersteund. Ondersteund, bijvoorbeeld: SELECT a AS b FROM ….
Relatie Ondersteund, bijvoorbeeld Account_vod__r.nvs_Country__c. Wordt niet ondersteund.

Gegevens ophalen met behulp van een where-component in de kolom DateTime

Wanneer u de SOQL- of SQL-query opgeeft, moet u letten op het verschil in datum/tijd-indeling. Bijvoorbeeld:

  • SOQL-voorbeeld: 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-voorbeeld: 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')}'}

Fout bij MALFORMED_QUERY: Afgekapt

Als u de fout 'MALFORMED_QUERY: Afgekapt' hebt bereikt, komt dit normaal gesproken doordat u de typekolom JunctionIdList in gegevens hebt en Salesforce beperkingen heeft voor het ondersteunen van dergelijke gegevens met een groot aantal rijen. Probeer de kolom JunctionIdList uit te sluiten of beperk het aantal rijen dat moet worden gekopieerd (u kunt partitioneren naar meerdere uitvoeringen van kopieeractiviteiten).

Toewijzing van gegevenstypen voor Salesforce

Wanneer u gegevens kopieert uit Salesforce, worden de volgende toewijzingen gebruikt van Salesforce-gegevenstypen naar tussentijdse gegevenstypen binnen de service intern. Zie Schema- en gegevenstypetoewijzingen voor meer informatie over hoe de kopieeractiviteit het bronschema en het gegevenstype toewijst aan de sink.

Salesforce-gegevenstype Tussentijdse servicegegevenstype
Automatisch nummer Tekenreeks
Checkbox Booleaans
Valuta Decimaal
Date DateTime
Datum/tijd DateTime
E-mail Tekenreeks
Id Tekenreeks
Opzoekrelatie Tekenreeks
Selectielijst met meerdere selecties Tekenreeks
Aantal Decimaal
Percentage Decimaal
Telefoon Tekenreeks
Picklist Tekenreeks
Tekst Tekenreeks
Tekstgebied Tekenreeks
Tekstgebied (lang) Tekenreeks
Tekstgebied (rijk) Tekenreeks
Tekst (versleuteld) Tekenreeks
URL Tekenreeks

Notitie

Het type Salesforce-nummer wordt toegewezen aan het decimale type in Azure Data Factory en Azure Synapse pijplijnen als een tussentijds gegevenstype van de service. Het decimale type respecteert de gedefinieerde precisie en schaal. Voor gegevens waarvan de decimalen de gedefinieerde schaal overschrijden, wordt de waarde afgerond in voorbeeldgegevens en kopiëren. Als u dergelijke precisieverlies in Azure Data Factory en Azure Synapse pijplijnen wilt voorkomen, kunt u overwegen om de decimalen te verhogen naar een redelijk grote waarde op de pagina Aangepaste velddefinitiebewerking van Salesforce.

Eigenschappen van opzoekactiviteit

Controleer de opzoekactiviteit voor meer informatie over de eigenschappen.

Volgende stappen

Zie Ondersteunde gegevensarchieven voor een lijst met gegevensarchieven die worden ondersteund als bronnen en sinks door de kopieeractiviteit.