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

Článek
10/16/2024

PLATÍ PRO: Azure Data Factory Azure Synapse Analytics

Tip

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

Tento článek popisuje, jak 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 Visual Studio, Invoke-RestMethod PowerShellu 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.

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ý:
- Azure Data Factory
- Azure Synapse
Vyhledejte REST a vyberte konektor REST.
Nakonfigurujte podrobnosti o službě, otestujte připojení a vytvořte novou propojenou službu.

Podrobnosti konfigurace konektoru

Následující části obsahují podrobnosti o vlastnostech, které 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.

Základní ověřování
Ověřování instančního objektu
Ověřování přihlašovacích údajů klienta OAuth2
Ověřování spravované identity přiřazené systémem
Ověřování spravované identity přiřazené uživatelem
Anonymní ověřování

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
servicePrincipalCredentialType	Zadejte typ přihlašovacích údajů, který se má použít pro ověřování instančního objektu. Povolené hodnoty jsou `ServicePrincipalKey` a `ServicePrincipalCert`.	No
Pro ServicePrincipalKey
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.	No
Pro ServicePrincipalCert
servicePrincipalEmbeddedCert	Zadejte certifikát s kódováním base64 vaší aplikace zaregistrovaný v Microsoft Entra ID a ujistěte se, že typ obsahu certifikátu je PKCS #12. Označte toto pole jako securestring , abyste ho mohli bezpečně uložit, nebo odkazovat na tajný klíč uložený ve službě Azure Key Vault. V této části se dozvíte, jak uložit certifikát ve službě Azure Key Vault.	No
servicePrincipalEmbeddedCertPassword	Zadejte heslo certifikátu, pokud je certifikát zabezpečený heslem. Označte toto pole jako securestring , abyste ho mohli bezpečně uložit, nebo odkazovat na tajný klíč uložený ve službě Azure Key Vault.	No

klient	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.net`napří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 1: Použití ověřování instančního klíče

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "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"
        }
    }
}

Příklad 2: Použití ověřování certifikátů instančního objektu

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "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"
        }
    }
}

Uložení certifikátu instančního objektu ve službě Azure Key Vault

Ve službě Azure Key Vault máte dvě možnosti uložení certifikátu instančního objektu:

Možnost 1
1. Převeďte certifikát instančního objektu na řetězec base64. Další informace najdete v tomto článku.
2. Uložte řetězec base64 jako tajný kód ve službě Azure Key Vault.
Možnost 2

Pokud nemůžete stáhnout certifikát ze služby Azure Key Vault, můžete pomocí této šablony uložit převedený certifikát instančního objektu jako tajný kód ve službě Azure Key Vault.

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.net`napří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.net`napří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 additionalHeadersrequestBody paginationRules 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.

Jímka REST toku dat

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.
Hlavičky. 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
Hlavičky. 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:

Rozsah není podporován v mapování toků dat.
[''] 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 . .
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:

Snímek obrazovky znázorňující jednu konfiguraci pro odesílání více požadavků, jejichž proměnné jsou v parametrech dotazu

nebo

Snímek obrazovky znázorňující další konfiguraci pro odesílání více požadavků, jejichž proměnné jsou v parametrech dotazu

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

Snímek obrazovky znázorňující jednu konfiguraci pro odesílání více požadavků, jejichž proměnné jsou v absolutní adrese URL

nebo

Snímek obrazovky znázorňující další konfiguraci pro odesílání více požadavků, jejichž proměnné jsou v absolutní adrese 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}" : "RANGE:0:100:10".

Snímek obrazovky s pravidlem stránkování pro odesílání více požadavků, jejichž proměnné jsou v záhlavích

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

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:

Snímek obrazovky s nastavením Maximální počet požadavků pro příklad 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í.

Snímek obrazovky znázorňující ukázky hlavičky HTTP, která odpovídá R F C 5988

Tip

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

Snímek obrazovky znázorňující, jak zakázat nastavení R F C 5988 pro příklad 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:

Snímek obrazovky znázorňující schéma odpovědi v příkladu 8

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

Snímek obrazovky znázorňující, jak nastavit pravidlo stránkování pro příklad 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:
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:

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>

Snímek obrazovky znázorňující formát odpovědi je X M L a další požadavek U R L je z textu odpovědi.

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

Snímek obrazovky znázorňující schéma odpovědi v příkladu 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:

Snímek obrazovky znázorňující nastavení pravidla stránkování pro Příklad 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.

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.

Sdílet prostřednictvím

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

Podporované funkce

Požadavky

Začínáme

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

Podrobnosti konfigurace konektoru

Vlastnosti propojené služby

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

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

Uložení certifikátu instančního objektu ve službě Azure Key Vault

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

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

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

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

Vlastnosti datové sady

Vlastnosti aktivity kopírování

REST jako zdroj

REST jako jímka

Mapování vlastností toku dat

Transformace zdroje

Transformace jímky

Ukázkový skript toku dat

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

Příklad 2:Variables in AbsoluteUrl

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

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.

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

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

Export odpovědi JSON tak, jak je

Schema mapping

Váš názor

Další materiály

Sdílet prostřednictvím

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

Podporované funkce

Požadavky

Začínáme

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

Podrobnosti konfigurace konektoru

Vlastnosti propojené služby

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

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

Uložení certifikátu instančního objektu ve službě Azure Key Vault

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

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

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

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

Vlastnosti datové sady

Vlastnosti aktivity kopírování

REST jako zdroj

REST jako jímka

Mapování vlastností toku dat

Transformace zdroje

Transformace jímky

Ukázkový skript toku dat

Podpora stránkování

Příklady pravidel stránkování

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

Příklad 2:Variables in AbsoluteUrl

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

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.

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

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

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

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.

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.

Export odpovědi JSON tak, jak je

Schema mapping

Související obsah

Váš názor

Další materiály