Kopiowanie danych z i do usługi Salesforce przy użyciu usługi Azure Data Factory lub Azure Synapse Analytics (starsza wersja)

Artykuł
05/11/2024

DOTYCZY: Azure Data Factory Azure Synapse Analytics

Napiwek

Wypróbuj usługę Data Factory w usłudze Microsoft Fabric — rozwiązanie analityczne typu all-in-one dla przedsiębiorstw. Usługa Microsoft Fabric obejmuje wszystko, od przenoszenia danych do nauki o danych, analizy w czasie rzeczywistym, analizy biznesowej i raportowania. Dowiedz się, jak bezpłatnie rozpocząć nową wersję próbną !

W tym artykule opisano sposób używania działania kopiowania w potokach usługi Azure Data Factory i Usługi Azure Synapse do kopiowania danych z i do usługi Salesforce. Jest on oparty na artykule Omówienie działania kopiowania, który przedstawia ogólne omówienie działania kopiowania.

Ważne

Nowy łącznik usługi Salesforce zapewnia ulepszoną natywną obsługę usługi Salesforce. Jeśli używasz starszego łącznika usługi Salesforce w swoim rozwiązaniu, uaktualnij łącznik usługi Salesforce przed 11 października 2024 r. Zapoznaj się z tą sekcją , aby uzyskać szczegółowe informacje na temat różnicy między starszą i najnowszą wersją.

Obsługiwane możliwości

Ten łącznik usługi Salesforce jest obsługiwany w następujących funkcjach:

Obsługiwane możliwości	IR
działanie Kopiuj (źródło/ujście)	(1) (2)
Działanie Lookup	(1) (2)

(1) Środowisko Azure Integration Runtime (2) Self-hosted Integration Runtime

Aby uzyskać listę magazynów danych obsługiwanych jako źródła lub ujścia, zobacz tabelę Obsługiwane magazyny danych.

W szczególności ten łącznik usługi Salesforce obsługuje następujące elementy:

Wersje Salesforce Developer, Professional, Enterprise lub Unlimited.
Kopiowanie danych z i do środowiska produkcyjnego, piaskownicy i domeny niestandardowej usługi Salesforce.

Uwaga

Ta funkcja obsługuje kopiowanie dowolnego schematu z wymienionych powyżej środowisk usługi Salesforce, w tym pakietu sukcesów organizacji non-profit (NPSP).

Łącznik usługi Salesforce jest oparty na interfejsie API REST/bulk usługi Salesforce. Podczas kopiowania danych z usługi Salesforce łącznik automatycznie wybiera między interfejsami API REST i zbiorczymi na podstawie rozmiaru danych — gdy zestaw wyników jest duży, interfejs API zbiorczy jest używany do lepszej wydajności; Możesz jawnie ustawić wersję interfejsu API używaną do odczytu/zapisu danych za pośrednictwem apiVersion właściwości w połączonej usłudze. Podczas kopiowania danych do usługi Salesforce łącznik używa interfejsu API BULK w wersji 1.

Uwaga

Łącznik nie ustawia już domyślnej wersji interfejsu API usługi Salesforce. Aby uzyskać zgodność z poprzednimi wersjami, jeśli została wcześniej ustawiona domyślna wersja interfejsu API, nadal działa. Wartość domyślna to 45.0 dla źródła i 40.0 dla ujścia.

Wymagania wstępne

Uprawnienia interfejsu API muszą być włączone w usłudze Salesforce.

Limity żądań usługi Salesforce

Usługa Salesforce ma limity zarówno dla łącznych żądań interfejsu API, jak i współbieżnych żądań interfejsu API. Należy uwzględnić następujące informacje:

Jeśli liczba równoczesnych żądań przekracza limit, występuje ograniczanie przepustowości i występują losowe błędy.
Jeśli łączna liczba żądań przekroczy limit, konto usługi Salesforce zostanie zablokowane przez 24 godziny.

W obu scenariuszach może zostać również wyświetlony komunikat o błędzie "REQUEST_LIMIT_EXCEEDED". Aby uzyskać więcej informacji, zobacz sekcję "Limity żądań interfejsu API" w temacie Limity deweloperów usługi Salesforce.

Rozpocznij

Aby wykonać działanie Kopiuj za pomocą potoku, możesz użyć jednego z następujących narzędzi lub zestawów SDK:

Tworzenie połączonej usługi z usługą Salesforce przy użyciu interfejsu użytkownika

Wykonaj poniższe kroki, aby utworzyć połączoną usługę z usługą Salesforce w interfejsie użytkownika witryny Azure Portal.

Przejdź do karty Zarządzanie w obszarze roboczym usługi Azure Data Factory lub Synapse i wybierz pozycję Połączone usługi, a następnie kliknij pozycję Nowy:
- Azure Data Factory
- Azure Synapse
Wyszukaj pozycję Salesforce i wybierz łącznik Salesforce.
Skonfiguruj szczegóły usługi, przetestuj połączenie i utwórz nową połączoną usługę.

Szczegóły konfiguracji łącznika

Poniższe sekcje zawierają szczegółowe informacje o właściwościach używanych do definiowania jednostek specyficznych dla łącznika usługi Salesforce.

Właściwości połączonej usługi

Następujące właściwości są obsługiwane w przypadku połączonej usługi Salesforce.

Właściwości	Opis	Wymagania
type	Właściwość type musi być ustawiona na Salesforce.	Tak
environmentUrl	Określ adres URL wystąpienia usługi Salesforce. - Wartość domyślna to `"https://login.salesforce.com"`. - Aby skopiować dane z piaskownicy, określ wartość `"https://test.salesforce.com"`. - Aby skopiować dane z domeny niestandardowej, określ na przykład `"https://[domain].my.salesforce.com"`.	Nie.
nazwa użytkownika	Określ nazwę użytkownika dla konta użytkownika.	Tak
hasło	Określ hasło dla konta użytkownika. Oznacz to pole jako element SecureString w celu bezpiecznego przechowywania go lub odwołuj się do wpisu tajnego przechowywanego w usłudze Azure Key Vault.	Tak
securityToken	Określ token zabezpieczający dla konta użytkownika. Aby dowiedzieć się więcej o tokenach zabezpieczających, zobacz Zabezpieczenia i interfejs API. Token zabezpieczający można pominąć tylko w przypadku dodania adresu IP środowiska Integration Runtime do listy zaufanych adresów IP w usłudze Salesforce. W przypadku korzystania z środowiska Azure IR zapoznaj się z adresami IP środowiska Azure Integration Runtime. Aby uzyskać instrukcje dotyczące uzyskiwania i resetowania tokenu zabezpieczającego, zobacz Uzyskiwanie tokenu zabezpieczającego. Oznacz to pole jako element SecureString w celu bezpiecznego przechowywania go lub odwołuj się do wpisu tajnego przechowywanego w usłudze Azure Key Vault.	Nie.
apiVersion	Określ wersję interfejsu API REST/bulk usługi Salesforce do użycia, np. `52.0`.	Nie.
connectVia	Środowisko Integration Runtime do nawiązania połączenia z magazynem danych. Jeśli nie zostanie określony, używa domyślnego środowiska Azure Integration Runtime.	Nie.

Przykład: Przechowywanie poświadczeń

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

Przykład: przechowywanie poświadczeń w usłudze 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"
        }
    }
}

Przykład: przechowywanie poświadczeń w usłudze Key Vault, a także środowiskoUrl i nazwa użytkownika

Należy pamiętać, że w ten sposób nie będzie już można edytować ustawień za pomocą interfejsu użytkownika. Pole wyboru Określ zawartość dynamiczną w formacie JSON zostanie zaznaczone i trzeba będzie edytować tę konfigurację ręcznie. Zaletą jest możliwość uzyskania wszystkich ustawień konfiguracji z usługi Key Vault zamiast parametryzacji niczego tutaj.

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

Właściwości zestawu danych

Aby uzyskać pełną listę sekcji i właściwości dostępnych do definiowania zestawów danych, zobacz artykuł Zestawy danych. Ta sekcja zawiera listę właściwości obsługiwanych przez zestaw danych usługi Salesforce.

Aby skopiować dane z i do usługi Salesforce, ustaw właściwość type zestawu danych na SalesforceObject. Obsługiwane są następujące właściwości.

Właściwości	Opis	Wymagania
type	Właściwość type musi być ustawiona na SalesforceObject.	Tak
objectApiName	Nazwa obiektu usługi Salesforce do pobrania danych.	Nie dla źródła, Tak dla ujścia

Ważne

Część "__c" nazwy interfejsu API jest wymagana dla dowolnego obiektu niestandardowego.

Zrzut ekranu przedstawiający nazwę interfejsu API połączenia usługi Salesforce.

Przykład:

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

Uwaga

W celu zapewnienia zgodności z poprzednimi wersjami: podczas kopiowania danych z usługi Salesforce, jeśli używasz poprzedniego zestawu danych typu "RelationalTable", nadal działa, gdy zobaczysz sugestię przełączenia się na nowy typ "SalesforceObject".

Właściwości	Opis	Wymagania
type	Właściwość type zestawu danych musi być ustawiona na Wartość RelationalTable.	Tak
tableName	Nazwa tabeli w usłudze Salesforce.	Nie (jeśli określono "zapytanie" w źródle działania)

Właściwości działania kopiowania

Aby uzyskać pełną listę sekcji i właściwości dostępnych do definiowania działań, zobacz artykuł Pipelines (Potoki ). Ta sekcja zawiera listę właściwości obsługiwanych przez źródło i ujście usługi Salesforce.

Salesforce jako typ źródła

Aby skopiować dane z usługi Salesforce, ustaw typ źródła w działaniu kopiowania na salesforceSource. Poniższe właściwości są obsługiwane w sekcji źródła działania kopiowania.

Właściwości	Opis	Wymagania
type	Właściwość type źródła działania kopiowania musi być ustawiona na SalesforceSource.	Tak
zapytanie	Użyj zapytania niestandardowego, aby odczytać dane. Możesz użyć zapytania SoQL (Salesforce Object Query Language) lub zapytania SQL-92. Zobacz więcej porad w sekcji porad dotyczących zapytań. Jeśli zapytanie nie zostanie określone, zostaną pobrane wszystkie dane obiektu Salesforce określonego w parametrze "objectApiName" w zestawie danych.	Nie (jeśli określono parametr "objectApiName" w zestawie danych)
readBehavior	Wskazuje, czy należy wykonywać zapytania dotyczące istniejących rekordów, czy wykonywać zapytania dotyczące wszystkich rekordów, w tym usuniętych rekordów. Jeśli nie zostanie określony, domyślne zachowanie jest poprzednie. Dozwolone wartości: zapytanie (domyślne), queryAll.	Nie.

Ważne

Część "__c" nazwy interfejsu API jest wymagana dla dowolnego obiektu niestandardowego.

Zrzut ekranu przedstawiający listę nazwa interfejsu API połączenia usługi Salesforce.

Przykład:

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

Uwaga

W przypadku zgodności z poprzednimi wersjami: podczas kopiowania danych z usługi Salesforce, jeśli używasz poprzedniej kopii typu "RelationalSource", źródło nadal działa, gdy zobaczysz sugestię przełączenia się na nowy typ "SalesforceSource".

Uwaga

Źródło usługi Salesforce nie obsługuje ustawień serwera proxy w własnym środowisku Integration Runtime, ale ujście nie jest obsługiwane.

Salesforce jako typ ujścia

Aby skopiować dane do usługi Salesforce, ustaw typ ujścia w działaniu kopiowania na salesforceSink. Poniższe właściwości są obsługiwane w sekcji ujścia działania kopiowania.

Właściwości	Opis	Wymagania
type	Właściwość type ujścia działania kopiowania musi być ustawiona na SalesforceSink.	Tak
writeBehavior	Zachowanie zapisu dla operacji. Dozwolone wartości to Insert i Upsert.	Nie (wartość domyślna to Wstaw)
externalIdFieldName	Nazwa pola identyfikatora zewnętrznego dla operacji upsert. Określone pole musi być zdefiniowane jako "Pole identyfikatora zewnętrznego" w obiekcie Salesforce. Nie może mieć wartości NULL w odpowiednich danych wejściowych.	Tak dla "Upsert"
writeBatchSize	Liczba wierszy zapisanych w usłudze Salesforce w każdej partii.	Nie (wartość domyślna to 5000)
ignoreNullValues	Wskazuje, czy podczas operacji zapisu mają być ignorowane wartości NULL z danych wejściowych. Dozwolone wartości to true i false. - Prawda: pozostaw dane w obiekcie docelowym bez zmian podczas wykonywania operacji upsert lub update. Wstaw zdefiniowaną wartość domyślną podczas wykonywania operacji wstawiania. - Fałsz: Zaktualizuj dane w obiekcie docelowym na wartość NULL podczas wykonywania operacji upsert lub update. Wstaw wartość NULL podczas wykonywania operacji wstawiania.	Nie (wartość domyślna to false)
maxConcurrentConnections	Górny limit połączeń współbieżnych ustanowionych z magazynem danych podczas uruchamiania działania. Określ wartość tylko wtedy, gdy chcesz ograniczyć połączenia współbieżne.	Nie

Przykład: ujście usługi Salesforce w działaniu kopiowania

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

Porady dotyczące zapytań

Pobieranie danych z raportu usługi Salesforce

Dane z raportów usługi Salesforce można pobrać, określając zapytanie jako {call "<report name>"}. Może to być na przykład "query": "{call \"TestReport\"}".

Pobieranie usuniętych rekordów z Kosza usługi Salesforce

Aby wykonać zapytanie dotyczące nietrwałych usuniętych rekordów z Kosza usługi Salesforce, można określić readBehavior jako queryAll.

Różnica między składnią zapytań SOQL i SQL

Podczas kopiowania danych z usługi Salesforce można użyć zapytania SOQL lub zapytania SQL. Należy pamiętać, że te dwa mają różną składnię i obsługę funkcji, nie mieszaj ich. Zaleca się użycie zapytania SOQL, które jest natywnie obsługiwane przez usługę Salesforce. W poniższej tabeli wymieniono główne różnice:

Składnia	Tryb SOQL	Tryb SQL
Wybór kolumny	Należy wyliczyć pola do skopiowania w zapytaniu, np. `SELECT field1, filed2 FROM objectname`	`SELECT *` jest obsługiwany oprócz zaznaczenia kolumny.
Cudzysłowu	Nie można cytować nazw plików/obiektów.	Nazwy pól/obiektów można cytować, np. `SELECT "id" FROM "Account"`
Format data/godzina	Zapoznaj się ze szczegółami tutaj i przykładami w następnej sekcji.	Zapoznaj się ze szczegółami tutaj i przykładami w następnej sekcji.
Wartości logiczne	Reprezentowane jako `False` i `True`, np. `SELECT … WHERE IsDeleted=True`.	Reprezentowane jako 0 lub 1, np. `SELECT … WHERE IsDeleted=1`.
Zmiana nazwy kolumny	Nieobsługiwane.	Obsługiwane, np. `SELECT a AS b FROM …`.
Relacja	Obsługiwane, np. `Account_vod__r.nvs_Country__c`.	Nieobsługiwane.

Pobieranie danych przy użyciu klauzuli where w kolumnie DateTime

Podczas określania zapytania SOQL lub SQL zwróć uwagę na różnicę w formacie DateTime. Na przykład:

Przykład 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')}
Przykład 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')}'}

Błąd MALFORMED_QUERY: Obcięte

Jeśli wystąpi błąd "MALFORMED_QUERY: Obcięte", zwykle jest to spowodowane tym, że kolumna typu JunctionIdList w danych i usługa Salesforce ma ograniczenie dotyczące obsługi takich danych z dużą liczbą wierszy. Aby rozwiązać ten problem, spróbuj wykluczyć kolumnę JunctionIdList lub ograniczyć liczbę wierszy do skopiowania (można podzielić na partycje wiele uruchomień działań kopiowania).

Mapowanie typów danych dla usługi Salesforce

Podczas kopiowania danych z usługi Salesforce następujące mapowania są używane z typów danych usługi Salesforce do typów danych tymczasowych w ramach usługi wewnętrznie. Aby dowiedzieć się, jak działanie kopiowania mapuje schemat źródłowy i typ danych na ujście, zobacz Mapowania schematu i typu danych.

Typ danych usługi Salesforce	Typ danych tymczasowych usługi
Automatyczny numer	String
Pole wyboru	Wartość logiczna
Waluta	Dziesiętne
Date	DateTime
Data/godzina	DateTime
Email	String
IDENTYFIKATOR	String
Relacja odnośnika	String
Lista wyboru wielokrotnego wyboru	String
Liczba	Dziesiętny
Procent	Dziesiętne
Phone	String
Picklist	String
Tekst	String
Obszar tekstu	String
Obszar tekstu (długi)	String
Obszar tekstu (sformatowany)	String
Tekst (zaszyfrowany)	String
URL	String

Uwaga

Typ numeru usługi Salesforce jest mapowanie na typ dziesiętny w potokach usługi Azure Data Factory i Azure Synapse jako typ danych tymczasowych usługi. Typ dziesiętny honoruje zdefiniowaną precyzję i skalę. W przypadku danych, których miejsca dziesiętne przekraczają zdefiniowaną skalę, jego wartość zostanie zaokrąglona w danych podglądu i skopiowaniu. Aby uniknąć utraty dokładności w potokach usługi Azure Data Factory i Azure Synapse, rozważ zwiększenie liczby miejsc dziesiętnych do dość dużej wartości na stronie Edycja definicji pola niestandardowego w usłudze Salesforce.

Właściwości działania wyszukiwania

Aby dowiedzieć się więcej o właściwościach, sprawdź działanie Wyszukiwania.

Następne kroki

Aby uzyskać listę magazynów danych obsługiwanych jako źródła i ujścia działania kopiowania, zobacz Obsługiwane magazyny danych.

Udostępnij za pośrednictwem

Kopiowanie danych z i do usługi Salesforce przy użyciu usługi Azure Data Factory lub Azure Synapse Analytics (starsza wersja)

Obsługiwane możliwości

Wymagania wstępne

Limity żądań usługi Salesforce

Rozpocznij

Tworzenie połączonej usługi z usługą Salesforce przy użyciu interfejsu użytkownika

Szczegóły konfiguracji łącznika

Właściwości połączonej usługi

Właściwości zestawu danych

Właściwości działania kopiowania

Salesforce jako typ źródła

Salesforce jako typ ujścia

Porady dotyczące zapytań

Pobieranie danych z raportu usługi Salesforce

Pobieranie usuniętych rekordów z Kosza usługi Salesforce

Różnica między składnią zapytań SOQL i SQL

Pobieranie danych przy użyciu klauzuli where w kolumnie DateTime

Błąd MALFORMED_QUERY: Obcięte

Mapowanie typów danych dla usługi Salesforce

Właściwości działania wyszukiwania

Następne kroki

Opinia

Dodatkowe zasoby