Kopiowanie i przekształcanie danych z i do punktu końcowego REST przy użyciu usługi Azure Data Factory

  • Artykuł

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 usłudze Azure Data Factory do kopiowania danych do i z punktu końcowego REST. Artykuł opiera się na artykule działaniu kopiowania w usłudze Azure Data Factory, który zawiera ogólne omówienie działania kopiowania.

Różnica między tym łącznikiem REST, łącznikiem HTTP i łącznikiem tabel sieci Web jest następująca:

  • Łącznik REST obsługuje kopiowanie danych z interfejsów API RESTful.
  • Łącznik HTTP jest ogólny w celu pobrania danych z dowolnego punktu końcowego HTTP, na przykład w celu pobrania pliku. Przed tym łącznikiem REST może się zdarzyć użycie łącznika HTTP do kopiowania danych z interfejsów API RESTful, które są obsługiwane, ale mniej funkcjonalne w porównaniu z łącznikiem REST.
  • Łącznik tabeli sieci Web wyodrębnia zawartość tabeli ze strony internetowej HTML.

Obsługiwane możliwości

Ten łącznik REST jest obsługiwany w przypadku następujących możliwości:

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

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

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

W szczególności ten ogólny łącznik REST obsługuje następujące elementy:

  • Kopiowanie danych z punktu końcowego REST przy użyciu metod GET lub POST i kopiowanie danych do punktu końcowego REST przy użyciu metod POST, PUT lub PATCH .
  • Kopiowanie danych przy użyciu jednego z następujących uwierzytelniania: anonimowe, podstawowe, jednostki usługi, poświadczeń klienta OAuth2, przypisanej przez system tożsamości zarządzanej i tożsamości zarządzanej przypisanej przez użytkownika.
  • Stronicowanie w interfejsach API REST.
  • W przypadku architektury REST jako źródła skopiuj odpowiedź JSON REST zgodnie z rzeczywistym użyciem lub przeanalizuj ją przy użyciu mapowania schematu. Obsługiwany jest tylko ładunek odpowiedzi w formacie JSON .

Napiwek

Aby przetestować żądanie pobierania danych przed skonfigurowaniem łącznika REST w usłudze Data Factory, zapoznaj się ze specyfikacją interfejsu API dla wymagań nagłówka i treści. Aby zweryfikować poprawność, możesz użyć narzędzi, takich jak Postman lub przeglądarka internetowa.

Wymagania wstępne

Jeśli magazyn danych znajduje się wewnątrz sieci lokalnej, sieci wirtualnej platformy Azure lub chmury prywatnej Amazon Virtual, musisz skonfigurować własne środowisko Integration Runtime , aby się z nim połączyć.

Jeśli magazyn danych jest zarządzaną usługą danych w chmurze, możesz użyć środowiska Azure Integration Runtime. Jeśli dostęp jest ograniczony do adresów IP zatwierdzonych w regułach zapory, możesz dodać adresy IP środowiska Azure Integration Runtime do listy dozwolonych.

Możesz również użyć funkcji środowiska Integration Runtime zarządzanej sieci wirtualnej w usłudze Azure Data Factory, aby uzyskać dostęp do sieci lokalnej bez instalowania i konfigurowania własnego środowiska Integration Runtime.

Aby uzyskać więcej informacji na temat mechanizmów zabezpieczeń sieci i opcji obsługiwanych przez usługę Data Factory, zobacz Strategie dostępu do danych.

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 REST przy użyciu interfejsu użytkownika

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

  1. 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 wybierz pozycję Nowe:

  2. Wyszukaj ciąg REST i wybierz łącznik REST.

    Select REST connector.

  3. Skonfiguruj szczegóły usługi, przetestuj połączenie i utwórz nową połączoną usługę.

    Configure REST linked service.

szczegóły konfiguracji Połączenie or

Poniższe sekcje zawierają szczegółowe informacje o właściwościach, których można użyć do definiowania jednostek usługi Data Factory specyficznych dla łącznika REST.

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

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

Właściwości Opis Wymagania
type Właściwość type musi być ustawiona na RestService. Tak
Adres URL Podstawowy adres URL usługi REST. Tak
enableServerCertificateValidation Czy podczas nawiązywania połączenia z punktem końcowym należy zweryfikować certyfikat TLS/SSL po stronie serwera. Nie.
(wartość domyślna to true)
authenticationType Typ uwierzytelniania używanego do nawiązywania połączenia z usługą REST. Dozwolone wartości to Anonimowe, Podstawowe, AadServicePrincipal, OAuth2ClientCredential i ManagedServiceIdentity. Ponadto można skonfigurować nagłówki uwierzytelniania we authHeaders właściwości. Zapoznaj się z odpowiednimi sekcjami poniżej, aby uzyskać więcej właściwości i przykładów. Tak
authHeaders Dodatkowe nagłówki żądań HTTP na potrzeby uwierzytelniania.
Aby na przykład użyć uwierzytelniania klucza interfejsu API, możesz wybrać typ uwierzytelniania jako "Anonimowy" i określić klucz interfejsu API w nagłówku.		 Nie.
connectVia Środowisko Integration Runtime do nawiązania połączenia z magazynem danych. Dowiedz się więcej w sekcji Wymagania wstępne . Jeśli nie zostanie określona, ta właściwość używa domyślnego środowiska Azure Integration Runtime. Nie.

Aby uzyskać szczegółowe informacje, zobacz odpowiednie sekcje dotyczące różnych typów uwierzytelniania.

Korzystanie z uwierzytelniania podstawowego

Ustaw właściwość authenticationType na Podstawowa. Oprócz właściwości ogólnych opisanych w poprzedniej sekcji określ następujące właściwości:

Właściwości Opis Wymagania
userName Nazwa użytkownika używana do uzyskiwania dostępu do punktu końcowego REST. Tak
hasło Hasło użytkownika ( wartość userName ). Oznacz to pole jako typ SecureString , aby bezpiecznie przechowywać je w usłudze Data Factory. Możesz również odwołać się do wpisu tajnego przechowywanego w usłudze Azure Key Vault. Tak

Przykład

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Korzystanie z uwierzytelniania jednostki usługi

Ustaw właściwość authenticationType na AadServicePrincipal. Oprócz właściwości ogólnych opisanych w poprzedniej sekcji określ następujące właściwości:

Właściwości Opis Wymagania
servicePrincipalId Określ identyfikator klienta aplikacji Microsoft Entra. Tak
servicePrincipalKey Określ klucz aplikacji Microsoft Entra. Oznacz to pole jako element SecureString , aby bezpiecznie przechowywać je w usłudze Data Factory lub odwoływać się do wpisu tajnego przechowywanego w usłudze Azure Key Vault. Tak
tenant Określ informacje o dzierżawie (nazwę domeny lub identyfikator dzierżawy), w ramach których znajduje się aplikacja. Pobierz go, umieszczając wskaźnik myszy w prawym górnym rogu witryny Azure Portal. Tak
aadResourceId Określ zasób Firmy Microsoft Entra, którego żądasz na potrzeby autoryzacji, na przykład https://management.core.windows.net. Tak
azureCloudType W przypadku uwierzytelniania jednostki usługi określ typ środowiska chmury platformy Azure, do którego zarejestrowano aplikację Firmy Microsoft Entra.
Dozwolone wartości to AzurePublic, AzureChina, AzureUsGovernment i AzureGermany. Domyślnie używane jest środowisko chmury fabryki danych.		 Nie.

Przykład

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Korzystanie z uwierzytelniania poświadczeń klienta OAuth2

Ustaw właściwość authenticationType na OAuth2ClientCredential. Oprócz właściwości ogólnych opisanych w poprzedniej sekcji określ następujące właściwości:

Właściwości Opis Wymagania
tokenEndpoint Punkt końcowy tokenu serwera autoryzacji w celu uzyskania tokenu dostępu. Tak
clientId Identyfikator klienta skojarzony z aplikacją. Tak
clientSecret Klucz tajny klienta skojarzony z aplikacją. Oznacz to pole jako typ SecureString , aby bezpiecznie przechowywać je w usłudze Data Factory. Możesz również odwołać się do wpisu tajnego przechowywanego w usłudze Azure Key Vault. Tak
zakres Wymagany zakres dostępu. Opisuje on, jakiego rodzaju dostęp zostanie zażądany. Nie.
zasób Docelowa usługa lub zasób, do którego zostanie żądany dostęp. Nie.

Przykład

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

Korzystanie z uwierzytelniania tożsamości zarządzanej przypisanej przez system

Ustaw właściwość authenticationType na Wartość ManagedServiceIdentity. Oprócz właściwości ogólnych opisanych w poprzedniej sekcji określ następujące właściwości:

Właściwości Opis Wymagania
aadResourceId Określ zasób Firmy Microsoft Entra, którego żądasz na potrzeby autoryzacji, na przykład https://management.core.windows.net. Tak

Przykład

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Korzystanie z uwierzytelniania tożsamości zarządzanej przypisanej przez użytkownika

Ustaw właściwość authenticationType na Wartość ManagedServiceIdentity. Oprócz właściwości ogólnych opisanych w poprzedniej sekcji określ następujące właściwości:

Właściwości Opis Wymagania
aadResourceId Określ zasób Firmy Microsoft Entra, którego żądasz na potrzeby autoryzacji, na przykład https://management.core.windows.net. Tak
poświadczenia Określ tożsamość zarządzaną przypisaną przez użytkownika jako obiekt poświadczeń. Tak

Przykład

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Używanie nagłówków uwierzytelniania

Ponadto można skonfigurować nagłówki żądań na potrzeby uwierzytelniania wraz z wbudowanymi typami uwierzytelniania.

Przykład: używanie uwierzytelniania klucza interfejsu API

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Właściwości zestawu danych

Ta sekcja zawiera listę właściwości, które obsługuje zestaw danych REST.

Aby uzyskać pełną listę sekcji i właściwości dostępnych do definiowania zestawów danych, zobacz Zestawy danych i połączone usługi.

Aby skopiować dane z interfejsu REST, obsługiwane są następujące właściwości:

Właściwości Opis Wymagania
type Właściwość type zestawu danych musi być ustawiona na RestResource. Tak
relativeUrl Względny adres URL zasobu, który zawiera dane. Jeśli ta właściwość nie zostanie określona, zostanie użyty tylko adres URL określony w definicji połączonej usługi. Łącznik HTTP kopiuje dane z połączonego adresu URL: [URL specified in linked service]/[relative URL specified in dataset]. Nie.

Jeśli ustawiono ustawienie requestMethod, additionalHeadersrequestBody i paginationRules w zestawie danych, nadal jest obsługiwane w miarę działania, podczas gdy sugerowane jest użycie nowego modelu w działaniu w przyszłości.

Przykład:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Właściwości działania kopiowania

Ta sekcja zawiera listę właściwości obsługiwanych przez źródło REST i ujście.

Aby uzyskać pełną listę sekcji i właściwości dostępnych do definiowania działań, zobacz Pipelines (Potoki).

REST jako źródło

Następujące właściwości są obsługiwane w sekcji źródło działania kopiowania:

Właściwości Opis Wymagania
type Właściwość type źródła działania kopiowania musi być ustawiona na wartość RestSource. Tak
requestMethod Metoda HTTP. Dozwolone wartości to GET (wartość domyślna) i POST. Nie.
dodatkowe ściągniki Dodatkowe nagłówki żądań HTTP. Nie.
requestBody Treść żądania HTTP. Nie.
paginationRules Reguły stronicowania do tworzenia żądań następnej strony. Szczegółowe informacje można znaleźć w sekcji pomocy technicznej dotyczącej stronicowania. Nie.
httpRequestTimeout Limit czasu ( wartość TimeSpan ) żądania HTTP w celu uzyskania odpowiedzi. Ta wartość to limit czasu pobierania odpowiedzi, a nie limit czasu odczytu danych odpowiedzi. Wartość domyślna to 00:01:40. Nie.
requestInterval Czas oczekiwania przed wysłaniem żądania na następną stronę. Wartość domyślna to 00:00:01 Nie.

Uwaga

Łącznik REST ignoruje dowolny nagłówek "Akceptuj" określony w pliku additionalHeaders. Ponieważ łącznik REST obsługuje tylko odpowiedź w formacie JSON, automatycznie wygeneruje nagłówek Accept: application/json.
Tablica obiektów jako treść odpowiedzi nie jest obsługiwana w stronicowaniu.

Przykład 1. Używanie metody Get z podziałem na strony

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Przykład 2: Używanie metody Post

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

REST jako ujście

Następujące 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 RestSink. Tak
requestMethod Metoda HTTP. Dozwolone wartości to POST (wartość domyślna), PUT i PATCH. Nie.
dodatkowe ściągniki Dodatkowe nagłówki żądań HTTP. Nie.
httpRequestTimeout Limit czasu ( wartość TimeSpan ) żądania HTTP w celu uzyskania odpowiedzi. Ta wartość to limit czasu pobierania odpowiedzi, a nie limit czasu zapisu danych. Wartość domyślna to 00:01:40. Nie.
requestInterval Czas interwału między różnymi żądaniami w milisekundach. Wartość interwału żądania powinna być liczbą z zakresu od [10, 60000]. Nie.
httpCompressionType Typ kompresji HTTP do użycia podczas wysyłania danych z optymalnym poziomem kompresji. Dozwolone wartości to brak i gzip. Nie.
writeBatchSize Liczba rekordów do zapisu w ujściu REST na partię. Wartość domyślna to 10000. Nie.

Łącznik REST jako ujście współdziała z interfejsami API REST, które akceptują kod JSON. Dane zostaną wysłane w formacie JSON przy użyciu następującego wzorca. W razie potrzeby możesz użyć mapowania schematu działania kopiowania, aby ponownie dostosować dane źródłowe do oczekiwanego ładunku przez interfejs API REST.

[
    { <data object> },
    { <data object> },
    ...
]

Przykład:

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

Właściwości przepływu mapowania danych

Interfejs REST jest obsługiwany w przepływach danych zarówno dla zestawów danych integracji, jak i wbudowanych zestawów danych.

Przekształcanie źródła

Właściwości Opis Wymagania
requestMethod Metoda HTTP. Dozwolone wartości to GET i POST. Tak
relativeUrl Względny adres URL zasobu, który zawiera dane. Jeśli ta właściwość nie zostanie określona, zostanie użyty tylko adres URL określony w definicji połączonej usługi. Łącznik HTTP kopiuje dane z połączonego adresu URL: [URL specified in linked service]/[relative URL specified in dataset]. Nie.
dodatkowe ściągniki Dodatkowe nagłówki żądań HTTP. Nie.
httpRequestTimeout Limit czasu ( wartość TimeSpan ) żądania HTTP w celu uzyskania odpowiedzi. Ta wartość to limit czasu pobierania odpowiedzi, a nie limit czasu zapisu danych. Wartość domyślna to 00:01:40. Nie.
requestInterval Czas interwału między różnymi żądaniami w milisekundach. Wartość interwału żądania powinna być liczbą z zakresu od [10, 60000]. Nie.
QueryParameters. request_query_parameter LUB QueryParameters['request_query_parameter'] Element "request_query_parameter" jest zdefiniowany przez użytkownika, który odwołuje się do jednej nazwy parametru zapytania w następnym adresie URL żądania HTTP. Nie.

Przekształcenie ujścia

Właściwości Opis Wymagania
dodatkowe ściągniki Dodatkowe nagłówki żądań HTTP. Nie.
httpRequestTimeout Limit czasu ( wartość TimeSpan ) żądania HTTP w celu uzyskania odpowiedzi. Ta wartość to limit czasu pobierania odpowiedzi, a nie limit czasu zapisu danych. Wartość domyślna to 00:01:40. Nie.
requestInterval Czas interwału między różnymi żądaniami w milisekundach. Wartość interwału żądania powinna być liczbą z zakresu od [10, 60000]. Nie.
httpCompressionType Typ kompresji HTTP do użycia podczas wysyłania danych z optymalnym poziomem kompresji. Dozwolone wartości to brak i gzip. Nie.
writeBatchSize Liczba rekordów do zapisu w ujściu REST na partię. Wartość domyślna to 10000. Nie.

Można ustawić metody usuwania, wstawiania, aktualizowania i upsert, a także względne dane wierszy do wysyłania do ujścia REST dla operacji CRUD.

Data flow REST sink

Przykładowy skrypt przepływu danych

Zwróć uwagę na użycie przekształcenia alter row przed ujściem w celu poinstruowania usługi ADF, jakiego typu akcji należy podjąć za pomocą ujścia REST. Tj. wstawianie, aktualizowanie, upsert, usuwanie.

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

Pomoc techniczna obsługi stronicowania

Podczas kopiowania danych z interfejsów API REST zwykle interfejs API REST ogranicza rozmiar ładunku odpowiedzi pojedynczego żądania w rozsądnej liczbie; chociaż zwraca dużą ilość danych, dzieli wynik na wiele stron i wymaga od wywołujących wysyłania kolejnych żądań w celu uzyskania następnej strony wyniku. Zwykle żądanie jednej strony jest dynamiczne i składa się z informacji zwróconych z odpowiedzi poprzedniej strony.

Ten ogólny łącznik REST obsługuje następujące wzorce stronicowania:

  • Bezwzględny lub względny adres URL następnego żądania = wartość właściwości w bieżącej treści odpowiedzi
  • Bezwzględny lub względny adres URL następnego żądania = wartość nagłówka w bieżących nagłówkach odpowiedzi
  • Parametr zapytania następnego żądania = wartość właściwości w bieżącej treści odpowiedzi
  • Parametr zapytania następnego żądania = wartość nagłówka w bieżących nagłówkach odpowiedzi
  • Nagłówek następnego żądania = wartość właściwości w bieżącej treści odpowiedzi
  • Nagłówek następnego żądania = wartość nagłówka w bieżących nagłówkach odpowiedzi

Reguły stronicowania są definiowane jako słownik w zestawie danych, który zawiera co najmniej jedną parę klucz-wartość z uwzględnieniem wielkości liter. Konfiguracja zostanie użyta do wygenerowania żądania rozpoczynającego się od drugiej strony. Łącznik przestanie iterować po kodzie stanu HTTP 204 (Bez zawartości) lub dowolnym z wyrażeń JSONPath w ciągu "paginationRules" zwraca wartość null.

Obsługiwane klucze w regułach stronicowania:

Key opis
Bezwzględnarl Wskazuje adres URL do wystawienia następnego żądania. Może to być bezwzględny adres URL lub względny adres URL.
QueryParameters. request_query_parameter LUB QueryParameters['request_query_parameter'] Element "request_query_parameter" jest zdefiniowany przez użytkownika, który odwołuje się do jednej nazwy parametru zapytania w następnym adresie URL żądania HTTP.
Nagłówki. request_header LUB nagłówki['request_header'] Element "request_header" jest zdefiniowany przez użytkownika, który odwołuje się do jednej nazwy nagłówka w następnym żądaniu HTTP.
EndCondition:end_condition Element "end_condition" jest zdefiniowany przez użytkownika, który wskazuje warunek, który zakończy pętlę stronicowania w następnym żądaniu HTTP.
MaxRequestNumber Wskazuje maksymalny numer żądania stronicowania. Pozostaw ją jako pustą oznacza brak limitu.
SupportRFC5988 Domyślnie jest ona ustawiona na wartość true, jeśli nie zdefiniowano reguły stronicowania. Tę regułę można wyłączyć, ustawiając supportRFC5988 wartość false lub usuń tę właściwość ze skryptu.

Obsługiwane wartości w regułach stronicowania:

Wartość Opis
Nagłówki. response_header LUB nagłówki['response_header'] Wartość "response_header" jest zdefiniowana przez użytkownika, która odwołuje się do jednej nazwy nagłówka w bieżącej odpowiedzi HTTP, której wartość będzie używana do wystawiania następnego żądania.
Wyrażenie JSONPath rozpoczynające się od "$" (reprezentujące katalog główny treści odpowiedzi) Treść odpowiedzi powinna zawierać tylko jeden obiekt JSON i tablicę obiektu, ponieważ treść odpowiedzi nie jest obsługiwana. Wyrażenie JSONPath powinno zwrócić pojedynczą wartość pierwotną, która będzie używana do wystawiania następnego żądania.

Uwaga

Reguły stronicowania przepływów mapowania danych różnią się od reguł kopiowania w następujących aspektach:

  1. Zakres nie jest obsługiwany w przepływach danych mapowania.
  2. [''] nie jest obsługiwany w przepływach danych mapowania. Zamiast tego użyj polecenia {} , aby uciec od znaku specjalnego. Na przykład , body.{@odata.nextLink}którego węzeł @odata.nextLink JSON zawiera znak . specjalny .
  3. Warunek końcowy jest obsługiwany w przepływach danych mapowania, ale składnia warunku różni się od niego w działaniu kopiowania. body służy do wskazywania treści odpowiedzi zamiast $. header służy do wskazywania nagłówka odpowiedzi zamiast headers. Oto dwa przykłady pokazujące tę różnicę:
    • Przykład 1:
      działanie Kopiuj: "EndCondition:$.data": "Empty"
      Przepływy danych mapowania: "EndCondition:body.data": "Empty"
    • Przykład 2:
      działanie Kopiuj: "EndCondition:headers.complete": "Exist"
      Przepływy danych mapowania: "EndCondition:header.complete": "Exist"

Przykłady reguł stronicowania

Ta sekcja zawiera listę przykładów ustawień reguł stronicowania.

Przykład 1: Zmienne w parametrach QueryParameters

W tym przykładzie przedstawiono kroki konfiguracji służące do wysyłania wielu żądań, których zmienne znajdują się w parametrach QueryParameters.

Wiele żądań:

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

Krok 1. Dane wejściowe sysparm_offset={offset} w podstawowym adresie URL lub względnym adresie URL, jak pokazano na poniższych zrzutach ekranu:

Screenshot showing one configuration to send multiple requests whose variables are in Query Parameters.

lub

Screenshot showing another configuration to send multiple requests whose variables are in Query Parameters.

Krok 2. Ustaw reguły stronicowania jako opcję 1 lub 2:

  • Opcja1: "QueryParameters.{ offset}" : "RANGE:0:10000:1000"

  • Opcja2: "AbsoluteUrl.{ offset}" : "RANGE:0:10000:1000"

Przykład 2:Zmienne w pliku AbsoluteUrl

W tym przykładzie przedstawiono kroki konfiguracji służące do wysyłania wielu żądań, których zmienne znajdują się w pliku AbsoluteUrl.

Wiele żądań:

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

Krok 1. Dane wejściowe {id} w podstawowym adresie URL na stronie konfiguracji połączonej usługi lub Względny adres URL w okienku połączenia zestawu danych.

Screenshot showing one configuration to send multiple requests whose variables are in Absolute Url.

lub

Screenshot showing another configuration to send multiple requests whose variables are in Absolute Url.

Krok 2. Ustawianie reguł stronicowania jako "AbsoluteUrl.{ id}" :"RANGE:1:100:1".

Przykład 3:Zmienne w nagłówkach

W tym przykładzie przedstawiono kroki konfiguracji służące do wysyłania wielu żądań, których zmienne znajdują się w nagłówkach.

Wiele żądań:
RequestUrl: https://example/table
Żądanie 1: Header(id->0)
Żądanie 2: Header(id->10)
......
Żądanie 100: Header(id->100)

Krok 1. Wprowadzanie {id} w dodatkowych nagłówkach.

Krok 2. Ustawianie reguł stronicowania jako "Nagłówki.{ id}" : "RARNGE:0:100:10".

Screenshot showing the pagination rule to send multiple requests whose variables are in Headers.

Przykład 4:Zmienne znajdują się w parametrach AbsoluteUrl/QueryParameters/Headers, zmienna końcowa nie jest wstępnie zdefiniowana, a warunek końcowy jest oparty na odpowiedzi

W tym przykładzie przedstawiono kroki konfiguracji służące do wysyłania wielu żądań, których zmienne znajdują się w parametrach AbsoluteUrl/QueryParameters/Headers, ale zmienna końcowa nie jest zdefiniowana. W przypadku różnych odpowiedzi różne ustawienia reguły warunku końcowego są wyświetlane w przykładzie 4.1-4.6.

Wiele żądań:

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
......

W tym przykładzie napotkano dwie odpowiedzi:

Odpowiedź 1:

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

Odpowiedź 2:

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

Krok 1. Ustaw zakres reguł stronicowania na przykład 1 i pozostaw koniec zakresu pusty jako "AbsoluteUrl.{ offset}": "RANGE:0::1000".

Krok 2. Ustaw różne reguły warunków końcowych zgodnie z różnymi ostatnimi odpowiedziami. Zobacz poniższe przykłady:

  • Przykład 4.1: stronicowanie kończy się, gdy wartość określonego węzła w odpowiedzi jest pusta

    Interfejs API REST zwraca ostatnią odpowiedź w następującej strukturze:

    {
    Data: []
}

    Ustaw regułę warunku końcowego na wartość "EndCondition:$.data": "Empty" , aby zakończyć stronicowanie, gdy wartość określonego węzła w odpowiedzi jest pusta.

    Screenshot showing the End Condition setting for Example 4.1.

  • Przykład 4.2: stronicowanie kończy się, gdy wartość określonego węzła w odpowiedzi nie istnieje

    Interfejs API REST zwraca ostatnią odpowiedź w następującej strukturze:

    {}

    Ustaw regułę warunku końcowego na wartość "EndCondition:$.data": "NonExist" , aby zakończyć stronicowanie, gdy wartość określonego węzła w odpowiedzi nie istnieje.

    Screenshot showing the End Condition setting for Example 4.2.

  • Przykład 4.3: stronicowanie kończy się, gdy istnieje wartość określonego węzła w odpowiedzi

    Interfejs API REST zwraca ostatnią odpowiedź w następującej strukturze:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Ustaw regułę warunku końcowego na " EndCondition:$. Complete": "Exist" , aby zakończyć stronicowanie, gdy istnieje wartość określonego węzła w odpowiedzi.

    Screenshot showing the End Condition setting for Example 4.3.

  • Przykład 4.4: stronicowanie kończy się, gdy wartość określonego węzła w odpowiedzi jest wartością const zdefiniowaną przez użytkownika

    Interfejs API REST zwraca odpowiedź w następującej strukturze:

    {
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}

    ......

    Ostatnia odpowiedź znajduje się w następującej strukturze:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Ustaw regułę warunku końcowego na " EndCondition:$. Complete": "Const:true" , aby zakończyć stronicowanie, gdy wartość określonego węzła w odpowiedzi jest wartością const zdefiniowaną przez użytkownika.

    Screenshot showing the End Condition setting for Example 4.4.

  • Przykład 4.5: stronicowanie kończy się, gdy wartość klucza nagłówka w odpowiedzi jest równa wartości const zdefiniowanej przez użytkownika

    Klucze nagłówka w odpowiedziach interfejsu API REST są wyświetlane w poniższej strukturze:

    Nagłówek odpowiedzi 1: header(Complete->0)
    ......
    Nagłówek ostatniej odpowiedzi: header(Complete->1)

    Ustaw regułę warunku końcowego jako "EndCondition:headers. Complete": "Const:1" , aby zakończyć stronicowanie, gdy wartość klucza nagłówka w odpowiedzi jest równa wartości const zdefiniowanej przez użytkownika.

    Screenshot showing the End Condition setting for Example 4.5.

  • Przykład 4.6: stronicowanie kończy się, gdy klucz istnieje w nagłówku odpowiedzi

    Klucze nagłówka w odpowiedziach interfejsu API REST są wyświetlane w poniższej strukturze:

    Nagłówek odpowiedzi 1: header()
    ......
    Nagłówek ostatniej odpowiedzi: header(CompleteTime->20220920)

    Ustaw regułę warunku końcowego jako "EndCondition:headers. CompleteTime": "Istnieje" , aby zakończyć stronicowanie, gdy klucz istnieje w nagłówku odpowiedzi.

    Screenshot showing the End Condition setting for Example 4.6.

Przykład 5: Ustawianie warunku końcowego w celu uniknięcia niekończących się żądań, gdy reguła zakresu nie jest zdefiniowana

W tym przykładzie przedstawiono kroki konfiguracji służące do wysyłania wielu żądań, gdy reguła zakresu nie jest używana. Warunek końcowy można ustawić na przykład 4.1-4.6, aby uniknąć niekończących się żądań. Interfejs API REST zwraca odpowiedź w następującej strukturze, w tym przypadku adres URL następnej strony jest reprezentowany w stronicowaniu.next.

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

Ostatnia odpowiedź to:

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

Krok 1. Ustaw reguły stronicowania jako "AbsoluteUrl": "$.paging.next".

Krok 2. Jeśli next w ostatniej odpowiedzi jest zawsze taki sam adres URL ostatniego żądania i nie jest pusty, żądania niekończące się będą wysyłane. Warunek końcowy może służyć do unikania niekończących się żądań. W związku z tym ustaw regułę warunku końcowego na przykład 4.1-4.6.

Przykład 6: Ustawianie maksymalnej liczby żądań, aby uniknąć niekończącego się żądania

Ustaw wartość MaxRequestNumber , aby uniknąć niekończącego się żądania, jak pokazano na poniższym zrzucie ekranu:

Screenshot showing the Max Request Number setting for Example 6.

Przykład 7: Reguła stronicowania RFC 5988 jest domyślnie obsługiwana

Zaplecze automatycznie pobierze następny adres URL na podstawie linków stylu RFC 5988 w nagłówku.

Screenshot showing samples of the http header that complies with R F C 5988.

Napiwek

Jeśli nie chcesz włączyć tej domyślnej reguły stronicowania, możesz ją ustawić supportRFC5988 na false lub po prostu usunąć w skrycie.

Screenshot showing how to disable R F C 5988 setting for Example 7.

Przykład 8. Następny adres URL żądania pochodzi z treści odpowiedzi podczas używania stronicowania w przepływach danych mapowania

W tym przykładzie przedstawiono sposób ustawiania reguły stronicowania i reguły warunku końcowego w przepływach danych mapowania, gdy następny adres URL żądania pochodzi z treści odpowiedzi.

Schemat odpowiedzi jest pokazany poniżej:

Screenshot showing the response schema of Example 8.

Reguły stronicowania powinny być ustawione na następujący zrzut ekranu:

Screenshot showing how to set the pagination rule for Example 8.

Domyślnie stronicowanie zostanie zatrzymane, gdy treść. {@odata.nextLink}** ma wartość null lub jest pusta.

Jeśli jednak wartość @odata.nextLink w ostatniej treści odpowiedzi jest równa ostatniemu adresowi URL żądania, doprowadzi to do nieskończonej pętli. Aby uniknąć tego warunku, zdefiniuj reguły warunków końcowych.

  • Jeśli wartość w ostatniej odpowiedzi jest pusta, można ustawić regułę warunku końcowego w następujący sposób:

    Screenshot showing setting the end condition rule when the last response is empty.

  • Jeśli wartość kompletnego klucza w nagłówku odpowiedzi równa true wskazuje koniec stronicowania, można ustawić regułę warunku końcowego w następujący sposób:

    Screenshot showing setting the end condition rule when the complete key in the response header equals to true indicates the end of pagination.

Przykład 9: Format odpowiedzi to XML, a następny adres URL żądania pochodzi z treści odpowiedzi podczas używania stronicowania w przepływach danych mapowania

W tym przykładzie przedstawiono sposób ustawiania reguły stronicowania w przepływach danych mapowania, gdy format odpowiedzi to XML, a następny adres URL żądania pochodzi z treści odpowiedzi. Jak pokazano na poniższym zrzucie ekranu, pierwszy adres URL to https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

Screenshot showing the response format is X M L and the next request U R L is from the response body.

Schemat odpowiedzi jest pokazany poniżej:

Screenshot showing the response schema of Example 9.

Składnia reguły stronicowania jest taka sama jak w przykładzie 8 i powinna być ustawiona jak poniżej w tym przykładzie:

Screenshot showing setting the pagination rule for Example 9.

Eksportowanie odpowiedzi JSON zgodnie z rzeczywistymi stanami

Ten łącznik REST umożliwia eksportowanie odpowiedzi JSON interfejsu API REST zgodnie z oczekiwaniami do różnych magazynów opartych na plikach. Aby uzyskać taką niezależną kopię schematu, pomiń sekcję "struktura" (nazywaną również schematem) w zestawie danych i mapowaniu schematu w działaniu kopiowania.

Mapowanie schematu

Aby skopiować dane z punktu końcowego REST do ujścia tabelarycznego, zapoznaj się z mapowaniem schematu.

Powiązana zawartość

Aby uzyskać listę magazynów danych obsługiwanych przez działanie kopiowania jako źródła i ujścia w usłudze Azure Data Factory, zobacz Obsługiwane magazyny danych i formaty.