Kopírování dat z a do Salesforce pomocí Azure Data Factory nebo Azure Synapse Analytics (starší verze)

Článek
05/11/2024

PLATÍ PRO: Azure Data Factory Azure Synapse Analytics

Tip

Vyzkoušejte si službu Data Factory v Microsoft Fabric, řešení pro analýzy typu all-in-one pro podniky. Microsoft Fabric zahrnuje všechno od přesunu dat až po datové vědy, analýzy v reálném čase, business intelligence a vytváření sestav. Přečtěte si, jak začít používat novou zkušební verzi zdarma.

Tento článek popisuje, jak používat aktivitu kopírování ve službě Azure Data Factory a kanálech Azure Synapse ke kopírování dat z a do Salesforce. Vychází z článku s přehledem aktivity kopírování, který představuje obecný přehled aktivity kopírování.

Důležité

Nový konektor Salesforce poskytuje vylepšenou nativní podporu Salesforce. Pokud ve svém řešení používáte starší verzi konektoru Salesforce, upgradujte prosím konektor Salesforce před 11. říjnem 2024. Podrobnosti o rozdílu mezi starší verzí a nejnovější verzí najdete v této části .

Podporované funkce

Tento konektor Salesforce je podporovaný pro následující funkce:

Podporované funkce	IR
aktivita Copy (zdroj/jímka)	(1) (2)
Aktivita Lookup	(1) (2)

(1) Prostředí Azure Integration Runtime (2) Místní prostředí Integration Runtime

Seznam úložišť dat podporovaných jako zdroje nebo jímky najdete v tabulce Podporované úložiště dat.

Konkrétně tento konektor Salesforce podporuje:

Edice Salesforce Developer, Professional, Enterprise nebo Unlimited
Kopírování dat z produkčního prostředí Salesforce, sandboxu a vlastní domény

Poznámka:

Tato funkce podporuje kopii libovolného schématu z výše uvedených prostředí Salesforce, včetně npsp (Nonprofit Success Pack ).

Konektor Salesforce je založený na rozhraní REST/Bulk API Salesforce. Při kopírování dat ze Salesforce konektor automaticky zvolí mezi rozhraními REST a Bulk API na základě velikosti dat – když je sada výsledků velká, použije se pro lepší výkon rozhraní Bulk API; Můžete explicitně nastavit verzi rozhraní API používanou ke čtení a zápisu dat prostřednictvím apiVersion vlastnosti v propojené službě. Při kopírování dat do Salesforce konektor používá rozhraní BULK API v1.

Poznámka:

Konektor už pro rozhraní Salesforce API nenastavuje výchozí verzi. Pokud byla dříve nastavena výchozí verze rozhraní API, bude zpětnou kompatibilitu fungovat. Výchozí hodnota je 45,0 pro zdroj a 40,0 pro jímku.

Požadavky

V Salesforce musí být povolené oprávnění rozhraní API.

Omezení požadavků Salesforce

Salesforce má omezení pro celkové požadavky rozhraní API i souběžné požadavky rozhraní API. Mějte na paměti následující body:

Pokud počet souběžných požadavků překročí limit, dojde k omezování a zobrazí se náhodná selhání.
Pokud celkový počet požadavků překročí limit, účet Salesforce se zablokuje po dobu 24 hodin.

V obou scénářích se také může zobrazit chybová zpráva "REQUEST_LIMIT_EXCEEDED". Další informace najdete v části Limity požadavků rozhraní API v omezeních pro vývojáře Salesforce.

Začínáme

K provedení aktivita Copy s kanálem můžete použít jeden z následujících nástrojů nebo sad SDK:

Vytvoření propojené služby pro Salesforce pomocí uživatelského rozhraní

Pomocí následujícího postupu vytvořte propojenou službu pro Salesforce v uživatelském rozhraní webu Azure Portal.

Přejděte na kartu Správa v pracovním prostoru Azure Data Factory nebo Synapse a vyberte Propojené služby a pak klikněte na Nový:
- Azure Data Factory
- Azure Synapse
Vyhledejte Salesforce a vyberte konektor Salesforce.
Nakonfigurujte podrobnosti o službě, otestujte připojení a vytvořte novou propojenou službu.

Podrobnosti konfigurace konektoru

Následující části obsahují podrobnosti o vlastnostech, které slouží k definování entit specifických pro konektor Salesforce.

Vlastnosti propojené služby

Pro propojenou službu Salesforce jsou podporovány následující vlastnosti.

Vlastnost	Popis	Povinní účastníci
type	Vlastnost typu musí být nastavená na Salesforce.	Ano
environmentUrl	Zadejte adresu URL instance Salesforce. - Výchozí hodnota je `"https://login.salesforce.com"`. – Chcete-li kopírovat data z sandboxu, zadejte `"https://test.salesforce.com"`. - Chcete-li kopírovat data z vlastní domény, zadejte například `"https://[domain].my.salesforce.com"`.	No
username	Zadejte uživatelské jméno pro uživatelský účet.	Ano
Heslo	Zadejte heslo pro uživatelský účet. Označte toto pole jako securestring, abyste ho mohli bezpečně uložit, nebo odkazovat na tajný klíč uložený ve službě Azure Key Vault.	Ano
securityToken	Zadejte token zabezpečení pro uživatelský účet. Obecné informace o tokenech zabezpečení najdete v tématu Zabezpečení a rozhraní API. Token zabezpečení je možné přeskočit jenom v případě, že přidáte IP adresu prostředí Integration Runtime do seznamu důvěryhodných IP adres v Salesforce. Pokud používáte Azure IR, projděte si IP adresy prostředí Azure Integration Runtime. Pokyny k získání a resetování tokenu zabezpečení najdete v tématu Získání tokenu zabezpečení. Označte toto pole jako securestring, abyste ho mohli bezpečně uložit, nebo odkazovat na tajný klíč uložený ve službě Azure Key Vault.	No
apiVersion	Zadejte verzi rozhraní REST/Bulk API salesforce, která se má použít, například `52.0`.	No
connectVia	Prostředí Integration Runtime , které se má použít pro připojení k úložišti dat. Pokud není zadaný, použije výchozí prostředí Azure Integration Runtime.	No

Příklad: Uložení přihlašovacích údajů

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

Příklad: Uložení přihlašovacích údajů ve službě 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"
        }
    }
}

Příklad: Ukládání přihlašovacích údajů ve službě Key Vault a také environmentUrl a uživatelské jméno

Mějte na paměti, že už nebudete moct uživatelské rozhraní používat k úpravám nastavení. Políčko Zadat dynamický obsah ve formátu JSON bude zaškrtnuté a budete muset tuto konfiguraci zcela upravit ručně. Výhodou je, že můžete odvodit všechna nastavení konfigurace ze služby Key Vault místo parametrizace čehokoli tady.

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

Vlastnosti datové sady

Úplný seznam oddílů a vlastností dostupných pro definování datových sad najdete v článku Datové sady . Tato část obsahuje seznam vlastností podporovaných datovou sadou Salesforce.

Pokud chcete kopírovat data z a do Salesforce, nastavte vlastnost typu datové sady na SalesforceObject. Podporují se následující vlastnosti.

Vlastnost	Popis	Povinní účastníci
type	Vlastnost typu musí být nastavena na SalesforceObject.	Ano
objectApiName	Název objektu Salesforce pro načtení dat.	Ne pro zdroj, Ano pro jímku

Důležité

Část "__c" názvu rozhraní API je nutná pro jakýkoli vlastní objekt.

Snímek obrazovky zobrazující název rozhraní API pro připojení Salesforce

Příklad:

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

Poznámka:

Z důvodu zpětné kompatibility: Při kopírování dat ze Salesforce, pokud použijete předchozí datovou sadu typu RelationalTable, bude dál fungovat, zatímco se zobrazí návrh přepnout na nový typ SalesforceObject.

Vlastnost	Popis	Povinní účastníci
type	Vlastnost typu datové sady musí být nastavena na RelationalTable.	Ano
tableName	Název tabulky v Salesforce	Ne (pokud je ve zdroji aktivity zadán dotaz)

Vlastnosti aktivity kopírování

Úplný seznam oddílů a vlastností dostupných pro definování aktivit najdete v článku Pipelines . Tato část obsahuje seznam vlastností podporovaných zdrojem a jímkou Salesforce.

Salesforce jako typ zdroje

Pokud chcete kopírovat data ze Salesforce, nastavte typ zdroje v aktivitě kopírování na SalesforceSource. Ve zdrojové části aktivity kopírování jsou podporovány následující vlastnosti.

Vlastnost	Popis	Povinní účastníci
type	Vlastnost typu zdroje aktivity kopírování musí být nastavena na SalesforceSource.	Ano
query	Ke čtení dat použijte vlastní dotaz. Můžete použít dotaz SOQL (Salesforce Object Query Language) nebo dotaz SQL-92. Další tipy najdete v části Tipy pro dotazy. Pokud není zadaný dotaz, načtou se všechna data objektu Salesforce zadaného v "objectApiName" v datové sadě.	Ne (pokud je v datové sadě zadáno "objectApiName")
readBehavior	Označuje, zda se má dotazovat na existující záznamy, nebo dotazovat všechny záznamy včetně odstraněných záznamů. Pokud není zadáno, výchozí chování je první. Povolené hodnoty: dotaz (výchozí), queryAll.	No

Důležité

Část "__c" názvu rozhraní API je nutná pro jakýkoli vlastní objekt.

Snímek obrazovky zobrazující seznam názvů rozhraní API pro připojení Salesforce

Příklad:

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

Poznámka:

Z důvodu zpětné kompatibility: Při kopírování dat ze Salesforce platí, že pokud použijete předchozí kopii typu RelationalSource, zdroj bude dál fungovat, zatímco uvidíte návrh přepnout na nový typ SalesforceSource.

Poznámka:

Zdroj Salesforce nepodporuje nastavení proxy serveru v místním prostředí Integration Runtime, ale jímka funguje.

Salesforce jako typ jímky

Pokud chcete kopírovat data do Salesforce, nastavte typ jímky v aktivitě kopírování na SalesforceSink. Následující vlastnosti jsou podporovány v části jímky aktivity kopírování.

Vlastnost	Popis	Povinní účastníci
type	Vlastnost typu jímky aktivity kopírování musí být nastavena na SalesforceSink.	Ano
writeBehavior	Chování zápisu operace. Povolené hodnoty jsou Insert a Upsert.	Ne (výchozí hodnota je Vložit)
externalIdFieldName	Název pole externího ID pro operaci upsertu. Zadané pole musí být definováno jako "Pole externího ID" v objektu Salesforce. V odpovídajících vstupních datech nemůže mít hodnoty NULL.	Ano pro upsert
writeBatchSize	Počet řádků dat zapsaných do Salesforce v každé dávce.	Ne (výchozí hodnota je 5 000)
ignoreNullValues	Určuje, zda se mají ignorovat hodnoty NULL ze vstupních dat během operace zápisu. Povolené hodnoty jsou true a false. - True: Při operaci upsertu nebo aktualizace ponechte data v cílovém objektu beze změny. Při operaci vložení vložte definovanou výchozí hodnotu. - False: Při operaci upsertu nebo aktualizace aktualizujte data v cílovém objektu na hodnotu NULL. Pokud provedete operaci vložení, vložte hodnotu NULL.	Ne (výchozí hodnota je false)
maxConcurrentConnections	Horní limit souběžných připojení vytvořených k úložišti dat během spuštění aktivity. Zadejte hodnotu pouze v případech, kdy chcete omezit souběžná připojení.	Ne

Příklad: Jímka Salesforce v aktivitě kopírování

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

Tipy pro dotazy

Načtení dat ze sestavy Salesforce

Data můžete načíst ze sestav Salesforce zadáním dotazu jako {call "<report name>"}. Příklad: "query": "{call \"TestReport\"}".

Načtení odstraněných záznamů z koše Salesforce

Pokud chcete dotazovat obnovitelně odstraněné záznamy z koše Salesforce, můžete zadat readBehavior jako queryAll.

Rozdíl mezi syntaxí dotazů SOQL a SQL

Při kopírování dat ze Salesforce můžete použít dotaz SOQL nebo dotaz SQL. Všimněte si, že tyto dvě verze mají jinou podporu syntaxe a funkčnosti, nesmíchejte je. Doporučujeme použít dotaz SOQL, který nativně podporuje Salesforce. Následující tabulka uvádí hlavní rozdíly:

Syntaxe	Režim SOQL	Režim SQL
Výběr sloupce	Potřebujete vytvořit výčet polí, která se mají zkopírovat v dotazu, například `SELECT field1, filed2 FROM objectname`	`SELECT *` podporuje se kromě výběru sloupce.
Uvozovky	Názvy souborů nebo objektů nelze uvozovat.	Názvy polí nebo objektů mohou být citovány, například `SELECT "id" FROM "Account"`
Formát data a času	Podrobnosti najdete tady a ukázky v další části.	Podrobnosti najdete tady a ukázky v další části.
Logické hodnoty	Reprezentováno jako `False` a `True`, např. `SELECT … WHERE IsDeleted=True`	Vyjádřeno jako 0 nebo 1, např. `SELECT … WHERE IsDeleted=1`
Přejmenování sloupců	Nepodporováno	Podporováno, například: `SELECT a AS b FROM …`.
Vztah	Podporováno, např. `Account_vod__r.nvs_Country__c`	Nepodporováno

Načtení dat pomocí klauzule where ve sloupci DateTime

Při zadání dotazu SOQL nebo SQL věnujte pozornost rozdílu ve formátu DateTime. Příklad:

Ukázka SOQL: 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')}
Ukázka SQL: 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')}'}

Chyba MALFORMED_QUERY: Zkráceno

Pokud dojde k chybě "MALFORMED_QUERY: Zkráceno", obvykle je to kvůli tomu, že máte sloupec typu JunctionIdList v datech a Salesforce má omezení na podporu těchto dat s velkým počtem řádků. Pokud chcete tento problém zmírnit, zkuste vyloučit sloupec JunctionIdList nebo omezit počet řádků pro kopírování (můžete rozdělit oddíly na více spuštění aktivit kopírování).

Mapování datových typů pro Salesforce

Při kopírování dat z Salesforce se následující mapování používají z datových typů Salesforce k dočasným datovým typům v rámci služby interně. Informace o tom, jak aktivita kopírování mapuje zdrojové schéma a datový typ na jímku, najdete v tématu Mapování schématu a datového typu.

Datový typ Salesforce	Dočasný datový typ služby
Automatické číslo	String
Checkbox	Logická hodnota
Měna	Desetinné číslo
Date	DateTime
Datum a čas	DateTime
Email	String
ID	String
Relace vyhledávání	String
Vícenásobný výběr rozevíracího seznamu	String
Počet	Des. místo
Procenta	Desetinné číslo
Telefon	String
Picklist	String
Text	String
Oblast textu	String
Textová oblast (dlouhá)	String
Textová oblast (formát RTF)	String
Text (šifrovaný)	String
URL	String

Poznámka:

Typ číslo salesforce se mapuje na desetinný typ v kanálech Azure Data Factory a Azure Synapse jako dočasný datový typ služby. Desetinný typ respektuje definovanou přesnost a měřítko. U dat, jejichž desetinná místa překročí definované měřítko, se jeho hodnota zaokrouhlí v datech náhledu a zkopíruje se. Abyste se vyhnuli takové ztrátě přesnosti v kanálech Azure Data Factory a Azure Synapse, zvažte zvýšení desetinných míst na přiměřeně velkou hodnotu na stránce Upravit definici vlastního pole salesforce.

Vlastnosti aktivity vyhledávání

Podrobnosti o vlastnostech najdete v aktivitě Vyhledávání.

Další kroky

Seznam úložišť dat podporovaných jako zdroje a jímky aktivitou kopírování najdete v tématu Podporované úložiště dat.

Sdílet prostřednictvím

Kopírování dat z a do Salesforce pomocí Azure Data Factory nebo Azure Synapse Analytics (starší verze)

Podporované funkce

Požadavky

Omezení požadavků Salesforce

Začínáme

Vytvoření propojené služby pro Salesforce pomocí uživatelského rozhraní

Podrobnosti konfigurace konektoru

Vlastnosti propojené služby

Vlastnosti datové sady

Vlastnosti aktivity kopírování

Salesforce jako typ zdroje

Salesforce jako typ jímky

Tipy pro dotazy

Načtení dat ze sestavy Salesforce

Načtení odstraněných záznamů z koše Salesforce

Rozdíl mezi syntaxí dotazů SOQL a SQL

Načtení dat pomocí klauzule where ve sloupci DateTime

Chyba MALFORMED_QUERY: Zkráceno

Mapování datových typů pro Salesforce

Vlastnosti aktivity vyhledávání

Další kroky

Váš názor

Další materiály