Kopírování a transformace dat z a do koncového bodu REST pomocí Azure Data Factory

  • Článek

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 pomocí aktivity kopírování ve službě Azure Data Factory kopírovat data z a do koncového bodu REST. Článek vychází z tématu Aktivita Copy ve službě Azure Data Factory, která představuje obecný přehled aktivity Copy.

Rozdíl mezi tímto konektorem REST, konektorem HTTP a konektorem webové tabulky:

  • Konektor REST konkrétně podporuje kopírování dat z rozhraní RESTful API.
  • Konektor HTTP je obecný pro načítání dat z libovolného koncového bodu HTTP, například pro stažení souboru. Před tímto konektorem REST se může stát, že pomocí konektoru HTTP zkopírujete data z rozhraní RESTful API, což je sice podporováno, ale méně funkční v porovnání s konektorem REST.
  • Konektor webové tabulky extrahuje obsah tabulky z webové stránky HTML.

Podporované funkce

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

Podporované funkce IR
aktivita Copy (zdroj/jímka) (1) (2)
Mapování toku dat (zdroj/jímka) (1)

(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 tématu Podporované úložiště dat.

Konkrétně tento obecný konektor REST podporuje:

  • Kopírování dat z koncového bodu REST pomocí metod GET nebo POST a kopírování dat do koncového bodu REST pomocí metod POST, PUT nebo PATCH .
  • Kopírování dat pomocí jednoho z následujících ověřování: anonymní, základní, instanční objekt, přihlašovací údaje klienta OAuth2, spravovaná identita přiřazená systémem a spravovaná identita přiřazená uživatelem.
  • Stránkování v rozhraních REST API
  • V případě REST jako zdroje zkopírujte odpověď REST JSON tak, jak je , nebo ji parsujte pomocí mapování schématu. Podporuje se pouze datová část odpovědi ve formátu JSON .

Tip

Pokud chcete otestovat požadavek na načtení dat před konfigurací konektoru REST ve službě Data Factory, přečtěte si o specifikaci rozhraní API pro požadavky na hlavičku a tělo. K ověření můžete použít nástroje, jako je Postman nebo webový prohlížeč.

Požadavky

Pokud se vaše úložiště dat nachází uvnitř místní sítě, virtuální sítě Azure nebo amazonového privátního cloudu, musíte nakonfigurovat místní prostředí Integration Runtime pro připojení k němu.

Pokud je vaše úložiště dat spravovanou cloudovou datovou službou, můžete použít Azure Integration Runtime. Pokud je přístup omezený na IP adresy schválené v pravidlech brány firewall, můžete do seznamu povolených přidat IP adresy prostředí Azure Integration Runtime.

K přístupu k místní síti bez nutnosti instalace a konfigurace místního prostředí Integration Runtime můžete také použít funkci Runtime integrace spravované virtuální sítě ve službě Azure Data Factory.

Další informace o mechanismech zabezpečení sítě a možnostech podporovaných službou Data Factory najdete v tématu Strategie přístupu k datům.

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 REST pomocí uživatelského rozhraní

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

  1. Přejděte na kartu Správa v pracovním prostoru Azure Data Factory nebo Synapse a vyberte Propojené služby a pak vyberte Nový:

  2. Vyhledejte REST a vyberte konektor REST.

    Select REST connector.

  3. Nakonfigurujte podrobnosti o službě, otestujte připojení a vytvořte novou propojenou službu.

    Configure REST linked service.

podrobnosti o konfiguraci Připojení oru

Následující části obsahují podrobnosti o vlastnostech, které můžete použít k definování entit služby Data Factory, které jsou specifické pro konektor REST.

Vlastnosti propojené služby

Pro propojenou službu REST jsou podporovány následující vlastnosti:

Vlastnost Popis Povinní účastníci
type Vlastnost typu musí být nastavena na RestService. Ano
url Základní adresa URL služby REST. Ano
enableServerCertificateValidation Určuje, jestli se má při připojování ke koncovému bodu ověřit certifikát TLS/SSL na straně serveru. No
(výchozí hodnota je true)
authenticationType Typ ověřování sloužící k připojení ke službě REST. Povolené hodnoty jsou Anonymní, Basic, AadServicePrincipal, OAuth2ClientCredential a ManagedServiceIdentity. Můžete také nakonfigurovat hlavičky ověřování ve authHeaders vlastnosti. Další vlastnosti a příklady najdete níže v odpovídajících částech. Ano
authHeaders Další hlavičky požadavku HTTP pro ověřování.
Pokud například chcete použít ověřování pomocí klíče rozhraní API, můžete vybrat typ ověřování jako Anonymní a zadat klíč rozhraní API v hlavičce.		 No
connectVia Prostředí Integration Runtime , které se má použít pro připojení k úložišti dat. Další informace najdete v části Požadavky . Pokud není zadána, tato vlastnost používá výchozí prostředí Azure Integration Runtime. No

Informace o různých typech ověřování najdete v odpovídajících částech.

Použití základního ověřování

Nastavte vlastnost authenticationType na Basic. Kromě obecných vlastností popsaných v předchozí části zadejte následující vlastnosti:

Vlastnost Popis Povinní účastníci
userName Uživatelské jméno, které se má použít pro přístup ke koncovému bodu REST. Ano
Heslo Heslo pro uživatele ( hodnota userName ). Toto pole označte jako typ SecureString , aby se bezpečně ukládaly ve službě Data Factory. Můžete také odkazovat na tajný klíč uložený ve službě Azure Key Vault. Ano

Příklad

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

Použití ověřování instančního objektu

Nastavte vlastnost authenticationType na AadServicePrincipal. Kromě obecných vlastností popsaných v předchozí části zadejte následující vlastnosti:

Vlastnost Popis Povinní účastníci
servicePrincipalId Zadejte ID klienta aplikace Microsoft Entra. Ano
servicePrincipalKey Zadejte klíč aplikace Microsoft Entra. Označte toto pole jako securestring pro bezpečné uložení ve službě Data Factory nebo odkazování na tajný klíč uložený ve službě Azure Key Vault. Ano
tenant Zadejte informace o tenantovi (název domény nebo ID tenanta), pod kterým se vaše aplikace nachází. Načtěte ho tak, že nainstalujete myší v pravém horním rohu webu Azure Portal. Ano
aadResourceId Zadejte prostředek Microsoft Entra, který požadujete pro autorizaci, https://management.core.windows.netnapříklad . Ano
azureCloudType V případě ověřování instančního objektu zadejte typ cloudového prostředí Azure, do kterého je zaregistrovaná vaše aplikace Microsoft Entra.
Povolené hodnoty jsou AzurePublic, AzureChina, AzureUsGovernment a AzureGermany. Ve výchozím nastavení se používá cloudové prostředí datové továrny.		 No

Příklad

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

Použití ověřování přihlašovacích údajů klienta OAuth2

Nastavte vlastnost authenticationType na OAuth2ClientCredential. Kromě obecných vlastností popsaných v předchozí části zadejte následující vlastnosti:

Vlastnost Popis Povinní účastníci
tokenEndpoint Koncový bod tokenu autorizačního serveru pro získání přístupového tokenu. Ano
clientId ID klienta přidružené k vaší aplikaci. Ano
clientSecret Tajný klíč klienta přidružený k vaší aplikaci. Toto pole označte jako typ SecureString , aby se bezpečně ukládaly ve službě Data Factory. Můžete také odkazovat na tajný klíč uložený ve službě Azure Key Vault. Ano
rozsah Rozsah požadovaného přístupu. Popisuje, jaký druh přístupu bude požadován. No
resource Cílová služba nebo prostředek, ke kterému se bude požadovat přístup. No

Příklad

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

Použití ověřování spravované identity přiřazené systémem

Nastavte vlastnost authenticationType na ManagedServiceIdentity. Kromě obecných vlastností popsaných v předchozí části zadejte následující vlastnosti:

Vlastnost Popis Povinní účastníci
aadResourceId Zadejte prostředek Microsoft Entra, který požadujete pro autorizaci, https://management.core.windows.netnapříklad . Ano

Příklad

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

Použití ověřování spravované identity přiřazené uživatelem

Nastavte vlastnost authenticationType na ManagedServiceIdentity. Kromě obecných vlastností popsaných v předchozí části zadejte následující vlastnosti:

Vlastnost Popis Povinní účastníci
aadResourceId Zadejte prostředek Microsoft Entra, který požadujete pro autorizaci, https://management.core.windows.netnapříklad . Ano
přihlašovací údaje Jako objekt přihlašovacích údajů zadejte spravovanou identitu přiřazenou uživatelem. Ano

Příklad

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

Použití ověřovacích hlaviček

Kromě toho můžete nakonfigurovat hlavičky požadavků pro ověřování spolu s integrovanými typy ověřování.

Příklad: Použití ověřování pomocí klíče rozhraní 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"
        }
    }
}

Vlastnosti datové sady

Tato část obsahuje seznam vlastností, které datová sada REST podporuje.

Úplný seznam oddílů a vlastností, které jsou k dispozici pro definování datových sad, najdete v tématu Datové sady a propojené služby.

Pokud chcete kopírovat data z REST, podporují se následující vlastnosti:

Vlastnost Popis Povinní účastníci
type Vlastnost typu datové sady musí být nastavena na RestResource. Ano
Relativeurl Relativní adresa URL prostředku, který obsahuje data. Pokud tato vlastnost není zadána, použije se pouze adresa URL zadaná v definici propojené služby. Konektor HTTP kopíruje data z kombinované adresy URL: [URL specified in linked service]/[relative URL specified in dataset]. No

Pokud jste nastavili requestMethoda additionalHeadersrequestBodypaginationRules v datové sadě se stále podporuje tak, jak je, zatímco se navrhuje používat nový model v aktivitě.

Příklad:

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

Vlastnosti aktivity kopírování

Tato část obsahuje seznam vlastností podporovaných zdrojem REST a jímkou.

Úplný seznam oddílů a vlastností, které jsou k dispozici pro definování aktivit, najdete v tématu Kanály.

REST jako zdroj

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 RestSource. Ano
requestMethod Metoda HTTP. Povolené hodnoty jsou GET (výchozí) a POST. No
additionalHeaders Další hlavičky požadavku HTTP No
requestBody Text požadavku HTTP. No
paginationRules Pravidla stránkování pro vytváření dalších požadavků na stránku. Podrobnosti najdete v části podpory stránkování. No
httpRequestTimeout Časový limit ( hodnota TimeSpan ) požadavku HTTP pro získání odpovědi. Tato hodnota je časový limit pro získání odpovědi, nikoli časový limit pro čtení dat odpovědi. Výchozí hodnota je 00:01:40. No
requestInterval Doba čekání před odesláním požadavku na další stránku. Výchozí hodnota je 00:00:01. No

Poznámka:

Konektor REST ignoruje všechny hlavičky Accept zadané v additionalHeaders. Protože konektor REST podporuje pouze odpověď ve formátu JSON, automaticky vygeneruje hlavičku Accept: application/json.
Pole objektu jako text odpovědi se ve stránkování nepodporuje.

Příklad 1: Použití metody Get se stránkováním

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

Příklad 2: Použití 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 jímka

V části jímky aktivity kopírování jsou podporovány následující vlastnosti:

Vlastnost Popis Povinní účastníci
type Vlastnost typu jímky aktivity kopírování musí být nastavena na RestSink. Ano
requestMethod Metoda HTTP. Povolené hodnoty jsou POST (výchozí), PUT a PATCH. No
additionalHeaders Další hlavičky požadavku HTTP No
httpRequestTimeout Časový limit ( hodnota TimeSpan ) požadavku HTTP pro získání odpovědi. Tato hodnota je časový limit pro získání odpovědi, nikoli vypršení časového limitu pro zápis dat. Výchozí hodnota je 00:01:40. No
requestInterval Doba intervalu mezi různými požadavky v milisekundách. Hodnota intervalu požadavku by měla být číslo mezi [10, 60000]. No
httpCompressionType Typ komprese HTTP, který se má použít při odesílání dat s optimální úrovní komprese. Povolené hodnoty nejsou žádné a gzip. No
writeBatchSize Počet záznamů pro zápis do jímky REST na dávku Výchozí hodnota je 1 0000. No

Konektor REST jako jímka funguje s rozhraními REST API, která přijímají JSON. Data se odešlou ve formátu JSON s následujícím vzorem. Podle potřeby můžete pomocí mapování schématu aktivity kopírování změnit tvar zdrojových dat tak, aby odpovídala očekávané datové části rozhraní REST API.

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

Příklad:

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

Mapování vlastností toku dat

Rest se podporuje v tocích dat pro integrační datové sady i vložené datové sady.

Transformace zdroje

Vlastnost Popis Povinní účastníci
requestMethod Metoda HTTP. Povolené hodnoty jsou GET a POST. Ano
Relativeurl Relativní adresa URL prostředku, který obsahuje data. Pokud tato vlastnost není zadána, použije se pouze adresa URL zadaná v definici propojené služby. Konektor HTTP kopíruje data z kombinované adresy URL: [URL specified in linked service]/[relative URL specified in dataset]. No
additionalHeaders Další hlavičky požadavku HTTP No
httpRequestTimeout Časový limit ( hodnota TimeSpan ) požadavku HTTP pro získání odpovědi. Tato hodnota je časový limit pro získání odpovědi, nikoli vypršení časového limitu pro zápis dat. Výchozí hodnota je 00:01:40. No
requestInterval Doba intervalu mezi různými požadavky v milisekundách. Hodnota intervalu požadavku by měla být číslo mezi [10, 60000]. No
QueryParameters. request_query_parameter NEBO QueryParameters['request_query_parameter'] "request_query_parameter" je definovaný uživatelem, který odkazuje na jeden název parametru dotazu v další adrese URL požadavku HTTP. No

Transformace jímky

Vlastnost Popis Povinní účastníci
additionalHeaders Další hlavičky požadavku HTTP No
httpRequestTimeout Časový limit ( hodnota TimeSpan ) požadavku HTTP pro získání odpovědi. Tato hodnota je časový limit pro získání odpovědi, nikoli vypršení časového limitu pro zápis dat. Výchozí hodnota je 00:01:40. No
requestInterval Doba intervalu mezi různými požadavky v milisekundách. Hodnota intervalu požadavku by měla být číslo mezi [10, 60000]. No
httpCompressionType Typ komprese HTTP, který se má použít při odesílání dat s optimální úrovní komprese. Povolené hodnoty nejsou žádné a gzip. No
writeBatchSize Počet záznamů pro zápis do jímky REST na dávku Výchozí hodnota je 1 0000. No

Můžete nastavit metody delete, insert, update a upsert a také data relativního řádku, která se mají odeslat do jímky REST pro operace CRUD.

Data flow REST sink

Ukázkový skript toku dat

Všimněte si použití transformace alter row před jímkou, abyste ADF řekli, jaký typ akce se má provést s jímkou REST. Tj. vložení, aktualizace, upsert, odstranění.

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

Podpora stránkování

Při kopírování dat z rozhraní REST API za normálních okolností omezuje rozhraní REST API velikost datové části odpovědi jednoho požadavku na přiměřené číslo; i když chcete vrátit velké množství dat, rozdělí výsledek na více stránek a vyžaduje, aby volající odeslali po sobě jdoucí žádosti, aby získali další stránku výsledku. Žádost o jednu stránku je obvykle dynamická a skládá se z informací vrácených z odpovědi předchozí stránky.

Tento obecný konektor REST podporuje následující vzory stránkování:

  • Absolutní nebo relativní adresa URL dalšího požadavku = hodnota vlastnosti v textu aktuální odpovědi
  • Absolutní nebo relativní adresa URL dalšího požadavku = hodnota hlavičky v záhlaví aktuální odpovědi
  • Parametr dotazu dalšího požadavku = hodnota vlastnosti v textu aktuální odpovědi
  • Parametr dotazu dalšího požadavku = hodnota hlavičky v záhlaví aktuální odpovědi
  • Hlavička dalšího požadavku = hodnota vlastnosti v textu aktuální odpovědi
  • Hlavička dalšího požadavku = hodnota hlavičky v aktuální hlavičce odpovědi

Pravidla stránkování jsou definována jako slovník v datové sadě, která obsahuje jeden nebo více párů klíč-hodnota rozlišujících malá a velká písmena. Konfigurace se použije k vygenerování požadavku počínaje druhou stránkou. Konektor přestane iterovat, když získá stavový kód HTTP 204 (bez obsahu) nebo některý z výrazů JSONPath ve výrazu paginationRules vrátí hodnotu null.

Podporované klíče v pravidlech stránkování:

Key Popis
AbsoluteUrl Označuje adresu URL k vydání dalšího požadavku. Může to být absolutní adresa URL nebo relativní adresa URL.
QueryParameters. request_query_parameter NEBO QueryParameters['request_query_parameter'] "request_query_parameter" je definovaný uživatelem, který odkazuje na jeden název parametru dotazu v další adrese URL požadavku HTTP.
Záhlaví. request_header OR Headers['request_header'] "request_header" je definovaný uživatelem, který odkazuje na jeden název hlavičky v dalším požadavku HTTP.
EndCondition:end_condition "end_condition" je definovaný uživatelem, což označuje podmínku, která ukončí smyčku stránkování v dalším požadavku HTTP.
MaxRequestNumber Určuje maximální číslo žádosti o stránkování. Nechejte ho prázdný, znamená to, že neexistuje žádný limit.
SupportRFC5988 Ve výchozím nastavení je toto nastavení nastaveno na hodnotu True, pokud není definováno žádné pravidlo stránkování. Toto pravidlo můžete zakázat nastavením supportRFC5988 na false nebo odebráním této vlastnosti ze skriptu.

Podporované hodnoty v pravidlech stránkování:

Hodnota Popis
Záhlaví. response_header OR Headers['response_header'] "response_header" je uživatelem definovaný, který odkazuje na jeden název hlavičky v aktuální odpovědi HTTP, jehož hodnota se použije k vydání dalšího požadavku.
Výraz JSONPath začínající na $(představující kořen textu odpovědi) Tělo odpovědi by mělo obsahovat pouze jeden objekt JSON a pole objektu, protože tělo odpovědi není podporováno. Výraz JSONPath by měl vrátit jednu primitivní hodnotu, která se použije k vydání dalšího požadavku.

Poznámka:

Pravidla stránkování v mapování toků dat se liší od pravidel kopírování v následujících aspektech:

  1. Rozsah není podporován v mapování toků dat.
  2. [''] v mapování toků dat se nepodporuje. Místo toho slouží {} k řídicímu speciálnímu znaku. Například , body.{@odata.nextLink}jehož uzel @odata.nextLink JSON obsahuje speciální znak . .
  3. Koncová podmínka se podporuje v mapování toků dat, ale syntaxe podmínky se liší od syntaxe v aktivitě kopírování. body slouží k označení textu odpovědi místo $. header slouží k označení hlavičky odpovědi místo headers. Tady jsou dva příklady, které ukazují tento rozdíl:
    • Příklad 1:
      aktivita Copy: EndCondition:$.data: "Empty"
      Mapování toků dat: EndCondition:body.data: "Empty"
    • Příklad 2:
      aktivita Copy: EndCondition:headers.complete: "Exist"
      Mapování toků dat: EndCondition:header.complete: "Exist"

Příklady pravidel stránkování

Tato část obsahuje seznam příkladů nastavení pravidel stránkování.

Příklad 1: Proměnné v queryParameters

Tento příklad poskytuje kroky konfigurace pro odesílání více požadavků, jejichž proměnné jsou v QueryParameters.

Více požadavků:

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: Vstup sysparm_offset={offset} do základní adresy URL nebo relativní adresy URL, jak je znázorněno na následujících snímcích obrazovky:

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

nebo

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

Krok 2: Nastavení pravidel stránkování jako možnosti 1 nebo 2:

  • Možnost1: QueryParameters.{ offset}" : "RANGE:0:10000:1000"

  • Možnost2: "AbsoluteUrl.{ offset}" : "RANGE:0:10000:1000"

Příklad 2:Variables in AbsoluteUrl

Tento příklad obsahuje kroky konfigurace pro odesílání více požadavků, jejichž proměnné jsou v absolutním seznamu.

Více požadavků:

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

Krok 1: Vstup {id} do základní adresy URL na stránce konfigurace propojené služby nebo relativní adresy URL v podokně připojení datové sady

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

nebo

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

Krok 2: Nastavení pravidel stránkování na hodnotu AbsoluteUrl.{ id}" :"RANGE:1:100:1".

Příklad 3:Proměnné v záhlavích

Tento příklad poskytuje kroky konfigurace pro odesílání více požadavků, jejichž proměnné jsou v hlavičkách.

Více požadavků:
RequestUrl: https://example/table
Žádost 1: Header(id->0)
Žádost 2: Header(id->10)
......
Žádost 100: Header(id->100)

Krok 1: Vstup {id} do dalších hlaviček

Krok 2: Nastavení pravidel stránkování na "Headers.{ id}" : "RARNGE:0:100:10".

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

Příklad 4:Proměnné jsou v AbsoluteUrl/QueryParameters/Headers, koncová proměnná není předem definovaná a koncová podmínka je založená na odpovědi.

Tento příklad poskytuje kroky konfigurace pro odesílání více požadavků, jejichž proměnné jsou v AbsoluteUrl/QueryParameters/Headers, ale koncová proměnná není definována. Pro různé odpovědi se v příkladu 4.1-4.6 zobrazují různá nastavení pravidla koncové podmínky.

Více požadavků:

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,
......

V tomto příkladu byly zjištěny dvě odpovědi:

Odpověď 1:

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

Odpověď 2:

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

Krok 1: Nastavte rozsah pravidel stránkování jako příklad 1 a ponechte konec oblasti prázdný jako AbsolutníUrl.{ offset}": "RANGE:0::1000".

Krok 2: Nastavte různá pravidla koncových podmínek podle různých posledních odpovědí. Podívejte se na následující příklady:

  • Příklad 4.1: Stránkování končí, když je hodnota konkrétního uzlu v odpovědi prázdná.

    Rozhraní REST API vrátí poslední odpověď v následující struktuře:

    {
    Data: []
}

    Nastavte pravidlo koncové podmínky na EndCondition:$.data: "Empty" pro ukončení stránkování, pokud je hodnota konkrétního uzlu v odpovědi prázdná.

    Screenshot showing the End Condition setting for Example 4.1.

  • Příklad 4.2: Stránkování končí, když hodnota konkrétního uzlu v odpovědi neexistuje.

    Rozhraní REST API vrátí poslední odpověď v následující struktuře:

    {}

    Nastavte pravidlo koncové podmínky jako EndCondition:$.data: NonExist pro ukončení stránkování, pokud hodnota konkrétního uzlu v odpovědi neexistuje.

    Screenshot showing the End Condition setting for Example 4.2.

  • Příklad 4.3: Stránkování končí, když existuje hodnota konkrétního uzlu v odpovědi.

    Rozhraní REST API vrátí poslední odpověď v následující struktuře:

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

    Nastavte pravidlo koncové podmínky jako EndCondition:$. Complete": "Exist" pro ukončení stránkování, pokud existuje hodnota konkrétního uzlu v odpovědi.

    Screenshot showing the End Condition setting for Example 4.3.

  • Příklad 4.4: Stránkování končí, když hodnota konkrétního uzlu v odpovědi je uživatelsky definovaná hodnota const.

    Rozhraní REST API vrátí odpověď v následující struktuře:

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

    ......

    Poslední odpověď je v následující struktuře:

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

    Nastavte pravidlo koncové podmínky jako EndCondition:$. Complete": "Const:true" pro ukončení stránkování, pokud hodnota konkrétního uzlu v odpovědi je uživatelsky definovaná hodnota const.

    Screenshot showing the End Condition setting for Example 4.4.

  • Příklad 4.5: Stránkování končí, když se hodnota klíče hlavičky v odpovědi rovná hodnotě const definované uživatelem

    Klíče hlaviček v odpovědích rozhraní REST API se zobrazují ve struktuře níže:

    Hlavička odpovědi 1: header(Complete->0)
    ......
    Poslední hlavička odpovědi: header(Complete->1)

    Nastavte pravidlo koncové podmínky jako EndCondition:headers. Complete": "Const:1" pro ukončení stránkování, pokud je hodnota klíče hlavičky v odpovědi rovna uživatelsky definované hodnotě const.

    Screenshot showing the End Condition setting for Example 4.5.

  • Příklad 4.6: Stránkování končí, když klíč existuje v hlavičce odpovědi.

    Klíče hlaviček v odpovědích rozhraní REST API se zobrazují ve struktuře níže:

    Hlavička odpovědi 1: header()
    ......
    Poslední hlavička odpovědi: header(CompleteTime->20220920)

    Nastavte pravidlo koncové podmínky jako EndCondition:headers. CompleteTime: "Exist" pro ukončení stránkování, pokud klíč existuje v hlavičce odpovědi.

    Screenshot showing the End Condition setting for Example 4.6.

Příklad 5:Nastavení koncové podmínky, aby se zabránilo nekonečným požadavkům, pokud není definováno pravidlo rozsahu

Tento příklad obsahuje kroky konfigurace pro odesílání více požadavků, pokud se pravidlo rozsahu nepoužívá. Koncovou podmínku lze nastavit v příkladu 4.1-4.6, abyste se vyhnuli nekonečným požadavkům. Rozhraní REST API vrátí odpověď v následující struktuře, v takovém případě je adresa URL další stránky reprezentována ve stránkování.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="
    }
}
...

Poslední odpověď je:

{
    "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: Nastavení pravidel stránkování na hodnotu AbsoluteUrl: $.paging.next

Krok 2: Pokud next je poslední odpověď vždy stejná s poslední adresou URL požadavku a není prázdná, budou se odesílat nekonečné požadavky. Koncovou podmínku je možné použít k zabránění nekonečným požadavkům. Proto nastavte pravidlo koncové podmínky na příklad 4.1-4.6.

Příklad 6:Nastavení maximálního počtu požadavků, aby se zabránilo nekonečnému požadavku

Nastavte MaxRequestNumber , abyste se vyhnuli nekonečnému požadavku, jak je znázorněno na následujícím snímku obrazovky:

Screenshot showing the Max Request Number setting for Example 6.

Příklad 7:Pravidlo stránkování RFC 5988 je ve výchozím nastavení podporováno.

Back-end automaticky získá další adresu URL na základě odkazů stylu RFC 5988 v záhlaví.

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

Tip

Pokud nechcete toto výchozí pravidlo stránkování povolit, můžete ho nastavit supportRFC5988false nebo jenom odstranit ve skriptu.

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

Příklad 8: Adresa URL dalšího požadavku pochází z textu odpovědi při použití stránkování v mapování toků dat.

Tento příklad uvádí, jak nastavit pravidlo stránkování a koncové pravidlo podmínky při mapování toků dat, když je adresa URL dalšího požadavku z textu odpovědi.

Schéma odpovědi je znázorněno níže:

Screenshot showing the response schema of Example 8.

Pravidla stránkování by se měla nastavit jako následující snímek obrazovky:

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

Ve výchozím nastavení se stránkování zastaví při textu. {@odata.nextLink}** má hodnotu null nebo je prázdná.

Pokud se ale hodnota @odata.nextLink v textu poslední odpovědi rovná poslední adrese URL požadavku, povede to k nekonečné smyčce. Chcete-li se této podmínce vyhnout, definujte pravidla koncových podmínek.

  • Pokud je hodnota v poslední odpovědi prázdná, můžete pravidlo koncové podmínky nastavit takto:

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

  • Pokud se hodnota celého klíče v hlavičce odpovědi rovná hodnotě true označuje konec stránkování, můžete pravidlo koncové podmínky nastavit takto:

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

Příklad 9: Formát odpovědi je XML a adresa URL dalšího požadavku pochází z textu odpovědi při použití stránkování v mapování toků dat.

Tento příklad uvádí, jak nastavit pravidlo stránkování v mapování toků dat, když je formát odpovědi XML a adresa URL dalšího požadavku je z textu odpovědi. Jak je znázorněno na následujícím snímku obrazovky, první adresa URL je 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.

Schéma odpovědi je znázorněno níže:

Screenshot showing the response schema of Example 9.

Syntaxe pravidla stránkování je stejná jako v příkladu 8 a měla by být nastavená níže v tomto příkladu:

Screenshot showing setting the pagination rule for Example 9.

Export odpovědi JSON tak, jak je

Tento konektor REST můžete použít k exportu odpovědi JSON rozhraní REST API tak, jak je, do různých úložišť založených na souborech. Pokud chcete takové kopírování nezávislé na schématu dosáhnout, přeskočte část "struktura" (označovaná také jako schéma) v datové sadě a mapování schématu v aktivitě kopírování.

Schema mapping

Pokud chcete zkopírovat data z koncového bodu REST do tabulkové jímky, přečtěte si mapování schématu.

Související obsah

Seznam úložišť dat, která aktivita kopírování podporuje jako zdroje a jímky ve službě Azure Data Factory, najdete v tématu Podporované úložiště a formáty dat.