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

Artikel
10/15/2024

VAN TOEPASSING OP: Azure Data Factory Azure Synapse Analytics

Tip

Probeer Data Factory uit in Microsoft Fabric, een alles-in-één analyseoplossing voor ondernemingen. Microsoft Fabric omvat alles, van gegevensverplaatsing tot gegevenswetenschap, realtime analyses, business intelligence en rapportage. Meer informatie over het gratis starten van een nieuwe proefversie .

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.

Belangrijk

De Salesforce V2-connector biedt verbeterde systeemeigen Salesforce-ondersteuning. Als u de Salesforce V1-connector in uw oplossing gebruikt, wordt u aangeraden om uw Salesforce-connector zo snel mogelijk te upgraden. Raadpleeg deze sectie voor meer informatie over het verschil tussen V2 en V1.

Ondersteunde mogelijkheden

Deze Salesforce-connector wordt ondersteund voor de volgende mogelijkheden:

Ondersteunde mogelijkheden	IR
Copy-activiteit (bron/sink)	(1) (2)
Activiteit Lookup	(1) (2)

(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 met name het volgende:

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

Notitie

Deze functie ondersteunt het kopiëren van een 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 expliciet de API-versie instellen die wordt gebruikt voor het lezen/schrijven van gegevens 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 geen standaardversie meer in voor Salesforce API. Als voor compatibiliteit met eerdere versies een standaard-API-versie is ingesteld, blijft deze werken. De standaardwaarde is 45.0 voor de bron en 40.0 voor sink.

Vereisten

DE 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. Let op de volgende punten:

Als het aantal gelijktijdige aanvragen de limiet overschrijdt, treedt er een 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-limieten voor ontwikkelaars 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 voor Salesforce in de gebruikersinterface van Azure Portal.

Blader naar het tabblad Beheren in uw Azure Data Factory- of Synapse-werkruimte en selecteer Gekoppelde services en klik vervolgens op Nieuw:
- Azure Data Factory
- Azure Synapse
Zoek naar Salesforce en selecteer de Salesforce-connector.
Configureer de servicedetails, test de verbinding en maak de nieuwe gekoppelde service.

Configuratiedetails van connector

De volgende secties bevatten details over eigenschappen die worden gebruikt om entiteiten te definiëren die specifiek zijn voor de Salesforce-connector.

Eigenschappen van gekoppelde service

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

Eigenschappen	Beschrijving	Vereist
type	De typeeigenschap moet worden ingesteld op Salesforce.	Ja
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 uit een aangepast domein wilt kopiëren, geeft u bijvoorbeeld `"https://[domain].my.salesforce.com"`op.	Nee
gebruikersnaam	Geef een gebruikersnaam op voor het gebruikersaccount.	Ja
password	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.	Ja
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 integration runtime toevoegt aan de lijst met vertrouwde IP-adressen in Salesforce. Als u Azure IR gebruikt, raadpleegt u IP-adressen van Azure Integration Runtime. Zie Een beveiligingstoken ophalen en opnieuw instellen voor instructies voor 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.	Nee
apiVersion	Geef de salesforce REST/bulk-API-versie op die moet worden gebruikt, bijvoorbeeld `52.0`.	Nee
connectVia	De Integration Runtime die moet worden gebruikt om verbinding te maken met het gegevensarchief. Als dit niet is opgegeven, wordt de standaard Azure Integration Runtime gebruikt.	Nee

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

Voorbeeld: Referenties opslaan in Key Vault, evenals omgevingUrl en gebruikersnaam

Als u dit doet, kunt u de gebruikersinterface niet meer gebruiken om instellingen te bewerken. Het selectievakje Dynamische inhoud opgeven in JSON-indeling wordt ingeschakeld en u moet deze configuratie volledig handmatig bewerken. Het voordeel is dat u ALLE configuratie-instellingen kunt afleiden uit de Key Vault in plaats van alles hier te parameteriseren.

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

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 van en naar Salesforce wilt kopiëren, stelt u de typeeigenschap van de gegevensset in op SalesforceObject. De volgende eigenschappen worden ondersteund.

Eigenschappen	Beschrijving	Vereist
type	De typeeigenschap moet worden ingesteld op SalesforceObject.	Ja
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.

Schermopname van de NAAM van de Salesforce-verbindings-API.

Voorbeeld:

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

Notitie

Voor compatibiliteit met eerdere versies: wanneer u gegevens kopieert uit Salesforce en u de vorige gegevensset van het type RelationalTable gebruikt, blijft deze werken terwijl u een suggestie ziet om over te schakelen naar het nieuwe type SalesforceObject.

Eigenschappen	Beschrijving	Vereist
type	De typeeigenschap van de gegevensset moet worden ingesteld op RelationalTable.	Ja
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 de kopieeractiviteit.

Eigenschappen	Beschrijving	Vereist
type	De typeeigenschap van de bron van de kopieeractiviteit moet worden ingesteld op SalesforceSource.	Ja
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 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 vorige. Toegestane waarden: query (standaard), queryAll.	Nee

Belangrijk

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

Schermopname van de lijst met naam van de 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 uit 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 naar Salesforce wilt kopiëren, stelt u het sinktype in de kopieeractiviteit in op SalesforceSink. De volgende eigenschappen worden ondersteund in de sectie sink voor kopieeractiviteiten.

Eigenschappen	Beschrijving	Vereist
type	De typeeigenschap van de sink voor kopieeractiviteit moet worden ingesteld op SalesforceSink.	Ja
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 van 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 wanneer u gelijktijdige verbindingen wilt beperken.	Nee

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 uit Salesforce, kunt u 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:

Syntaxis	SOQL-modus	SQL-modus
Kolomselectie	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-/tijdnotatie	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 rekening houden met het verschil in de datum/tijd-indeling. Voorbeeld:

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' krijgt, komt dit normaal gesproken doordat u de kolom JunctionIdList-type 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 het aantal te kopiëren rijen te beperken (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	String
Selectievakje	Booleaanse waarde
Valuta	Decimal
Datum	Datum en tijd
Datum/tijd	Datum en tijd
Email	String
Id	String
Opzoekrelatie	String
Selectielijst met meerdere selecties	String
Nummer	Decimaal
Procent	Decimal
Telefoonnummer	String
Picklist	String
Tekst	String
Tekstgebied	String
Tekstgebied (lang)	String
Tekstgebied (rich)	String
Tekst (versleuteld)	String
URL	String

Notitie

Het salesforce-nummertype wordt toegewezen aan het decimale type in Azure Data Factory- en Azure Synapse-pijplijnen als een tijdelijk gegevenstype voor de service. Het decimale type respecteert de gedefinieerde precisie en schaal. Voor gegevens waarvan de decimalen de gedefinieerde schaal overschrijden, wordt de waarde ervan 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 tot een redelijk grote waarde op de pagina Aangepaste velddefinitie bewerken van Salesforce.

Eigenschappen van opzoekactiviteit

Als u meer wilt weten over de eigenschappen, controleert u de lookup-activiteit.

Volgende stappen

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

Delen via

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

Ondersteunde mogelijkheden

Vereisten

Limieten voor Salesforce-aanvragen

Aan de slag

Een gekoppelde service maken met Salesforce met behulp van de gebruikersinterface

Configuratiedetails van connector

Eigenschappen van gekoppelde service

Eigenschappen van gegevensset

Eigenschappen van de kopieeractiviteit

Salesforce als brontype

Salesforce als sinktype

Querytips

Gegevens ophalen uit een Salesforce-rapport

Verwijderde records ophalen uit de Prullenbak van Salesforce

Verschil tussen SOQL en SQL-querysyntaxis

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

Fout bij MALFORMED_QUERY: Afgekapt

Toewijzing van gegevenstypen voor Salesforce

Eigenschappen van opzoekactiviteit

Volgende stappen

Feedback

Aanvullende resources