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

VZTAHUJE SE NA: Azure Data Factory Azure Synapse Analytics

Návod

Data Factory v Microsoft Fabric je nová generace Azure Data Factory s jednodušší architekturou, integrovanou AI a novými funkcemi. Pokud s integrací dat začínáte, začněte Fabric Data Factory. Stávající úlohy ADF lze upgradovat na Fabric pro přístup k novým funkcím v oblastech datové vědy, analýz v reálném čase a vytváření sestav.

• Začněte bezplatnou zkušební verzi Fabric.
• Upgrade z Azure Data Factory na Data Factory v Microsoft Fabric.

Tento článek popisuje, jak používat aktivitu kopírování v Azure Data Factory ke kopírování dat z koncového bodu REST a do koncového bodu REST. Článek vychází z aktivity Copy v Azure Data Factory, který představuje obecný přehled aktivity kopírování.

Poznámka:

Tento konektor je také k dispozici ve službě Data Factory v Microsoft Fabric. Informace o konfiguraci a funkcích specifických pro Fabric najdete v dokumentaci ke konektoru FABRIC REST.

Rozdíly mezi tímto REST konektorem, HTTP konektorem a webovou tabulkou jsou:

• Konektor REST konkrétně podporuje kopírování dat z rozhraní RESTful API.
• HTTP konektor je obecný pro získání dat z libovolného HTTP endpointu, například pro stažení souboru. Před tímto REST konektorem jste mohli použít HTTP konektor ke kopírování dat z RESTful API, což je podporováno, ale méně funkční než REST konektor.
• 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) Azure Integration Runtime (2) Lokálně hostované 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 REST endpointu pomocí metod GET nebo POST a kopírování dat na REST endpoint pomocí metod POST,PUT nebo PATCH .
• Kopírování dat pomocí jedné z následujících autentizací: anonymní, základní, principál služby, klientské přihlašovací údaje OAuth2, spravovaná identita přiřazená systému 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 .

Návod

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ě, Azure virtuální sítě, nebo Amazon Virtual Private Cloud, musíte pro připojení nakonfigurovat self-hosted Integration Runtime.

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 Azure Integration Runtime.

Funkci managed virtual network Integration Runtime můžete také použít v Azure Data Factory pro přístup k místní síti bez nutnosti instalace a konfigurace místního prostředí Integration Runtime.

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í aktivity kopírování pomocí datového kanálu můžete použít jeden z následujících nástrojů nebo sad SDK:

• Nástroj pro kopírování dat
• portál Azure
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• šablona Azure Resource Manager

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í portálu Azure.

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

   Azure Data Factory

   

   Azure Synapse

   

2. Vyhledejte REST a vyberte konektor REST.

   

3. 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	Požadováno
typ	Vlastnost typu musí být nastavena na RestService.	Ano
adresa URL	Základní adresa URL služby REST.	Ano
PovolitOvěřováníCertifikátuServeru	Určuje, jestli se má při připojování ke koncovému bodu ověřit certifikát TLS/SSL na straně serveru.	Ne (výchozí hodnota je true)
typ autentizace	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í v vlastnosti authHeaders. Další vlastnosti a příklady najdete níže v odpovídajících částech.	Ano
autentizační hlavičky	Další hlavičky požadavků 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.	Ne
connectVia	Integration Runtime 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í Azure Integration Runtime.	Ne

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

• Základní ověřování
• Ověřování principálu služby
• OAuth2 ověření klientských přihlašovacích údajů
• 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	Požadováno
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é odložit tajný kód uložený v 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í klientské identity

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

Vlastnost	Popis	Požadováno
Identifikátor hlavní služby	Zadejte ID klienta aplikace Microsoft Entra.	Ano
Typ přihlašovacích údajů služby Principal	Zadejte typ přihlašovacích údajů, které se mají použít pro ověřování principálu služby. Povolené hodnoty jsou ServicePrincipalKey a ServicePrincipalCert.	Ne
Pro ServicePrincipalKey
Klíč hlavního služby (servicePrincipalKey)	Zadejte klíč aplikace Microsoft Entra. Toto pole označte jako SecureString pro bezpečné uložení ve službě Data Factory nebo reference tajného kódu uloženého v Azure Key Vault.	Ne
Pro ServicePrincipalCert
vestavěný certifikát hlavní služby	Zadejte certifikát zakódovaný v base64 vaší aplikace zaregistrovaný v Microsoft Entra ID a ujistěte se, že typ obsahu certifikátu je PKCS č. 12. Toto pole označte jako SecureString pro bezpečné uložení nebo reference tajného kódu uloženého v Azure Key Vault. V tomto section se dozvíte, jak certifikát uložit v Azure Key Vault.	Ne
heslo zabudovaného certifikátu principála služby	Zadejte heslo certifikátu, pokud je certifikát zabezpečený heslem. Toto pole označte jako SecureString pro bezpečné uložení nebo reference tajného kódu uloženého v Azure Key Vault.	Ne
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 umístíte kurzor myši do pravého horního rohu portálu Azure.	Ano
aadResourceId	Zadejte Microsoft Entra prostředek, o jehož autorizaci žádáte, například https://management.core.windows.net.	Ano
typ cloudu Azure	V případě ověřování aplikačního objektu zadejte typ prostředí Azure cloudu, do kterého je vaše aplikace Microsoft Entra zaregistrována. Povolené hodnoty jsou AzurePublic, AzureChina, AzureUsGovernment a AzureGermany. Ve výchozím nastavení se používá cloudové prostředí datové továrny.	Ne

Příklad 1: Použití ověřování klíčem hlavní služby

{
    "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átem služebního principálu

{
    "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 v Azure Key Vault

Máte dvě možnosti, jak uložit certifikát principála služby v Azure Key Vault:

• Možnost 1

  1. Převeďte certifikát služeb na řetězec base64. Další informace najdete v tomto článku.

  2. Uložte řetězec base64 jako tajný kód v Azure Key Vault.

     

     

• Možnost 2

  Pokud nemůžete stáhnout certifikát z Azure Key Vault, můžete použít tento template a uložit převedený certifikát instančního objektu jako tajný kód v Azure Key Vault.

  

Použijte ověření klientských přihlašovacích údajů OAuth2

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

Vlastnost	Popis	Požadováno
koncový bod tokenu	Koncový bod tokenu autorizačního serveru pro získání přístupového tokenu.	Ano
ID klienta	ID klienta přidružené k vaší aplikaci.	Ano
klíč klienta	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é odložit tajný kód uložený v Azure Key Vault.	Ano
obor	Rozsah požadovaného přístupu. Popisuje, jaký druh přístupu bude požadován.	Ne
prostředek	Cílová služba nebo prostředek, ke kterému se bude požadovat přístup.	Ne

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

Využ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	Požadováno
aadResourceId	Zadejte Microsoft Entra prostředek, o jehož autorizaci žádáte, například https://management.core.windows.net.	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	Požadováno
aadResourceId	Zadejte Microsoft Entra prostředek, o jehož autorizaci žádáte, například https://management.core.windows.net.	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	Požadováno
typ	Vlastnost typu datové sady musí být nastavena na RestResource.	Ano
relativní URL	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].	Ne

Pokud nastavíte requestMethod, additionalHeaders, requestBody, a paginationRules v datové sadě, kopírovací operace je stále podporuje as-is, i když byste měli nový model používat v aktivitě do budoucna.

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 částí a vlastností, které jsou k dispozici pro definování aktivit, najdete v tématu Pipelines.

REST jako zdroj

Ve zdrojové části sekce kopírování jsou podporovány následující vlastnosti:

Vlastnost	Popis	Požadováno
typ	Vlastnost typu zdroje aktivity kopírování musí být nastavena na RestSource.	Ano
metoda požadavku	Metoda HTTP. Povolené hodnoty jsou GET (výchozí) a POST.	Ne
dodatečná záhlaví	Další hlavičky požadavku HTTP.	Ne
requestBody	Text požadavku HTTP.	Ne
pravidla stránkování	Pravidla stránkování pro vytváření následujících požadavků na stránky. Podrobnosti najdete v části podpora stránkování.	Ne
časový limit požadavku HTTP	Č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.	Ne
requestInterval	Doba čekání před odesláním požadavku na další stránku. Výchozí hodnota je 00:00:01.	Ne

Poznámka:

REST konektor ignoruje jakoukoli Accept hlavičku zadánou v .additionalHeaders Protože podporuje pouze JSON odpovědi, automaticky nastaví hlavičku na Accept: application/json.
Stránkování není podporováno u odpovědí rozhraní REST API, kde struktura nejvyšší úrovně je pole JSON.

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 sekci jímky aktivity kopírování jsou podporovány následující vlastnosti:

Vlastnost	Popis	Požadováno
typ	Vlastnost typu jímky aktivity kopírování musí být nastavena na RestSink.	Ano
metoda požadavku	Metoda HTTP. Povolené hodnoty jsou POST (výchozí), PUT a PATCH.	Ne
dodatečná záhlaví	Další hlavičky požadavku HTTP.	Ne
časový limit požadavku HTTP	Č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 zápis dat. Výchozí hodnota je 00:01:40.	Ne
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].	Ne
typ komprese HTTP	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.	Ne
writeBatchSize	Počet záznamů pro zápis do jímky REST na dávku Výchozí hodnota je 1 0000.	Ne

Konektor REST jako jímka funguje s rozhraními REST API, která přijímají JSON. Data jsou odesílána v JSON podle následujícího vzoru. Podle potřeby použijte mapování schématu kopírování k přetvoření zdrojových dat tak, aby odpovídala očekávanému payloadu 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	Požadováno
metoda požadavku	Metoda HTTP. Povolené hodnoty jsou GET a POST.	Ano
relativní URL	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].	Ne
dodatečná záhlaví	Další hlavičky požadavku HTTP.	Ne
časový limit požadavku HTTP	Č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.	Ne
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].	Ne
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.	Ne

Transformace jímky

Vlastnost	Popis	Požadováno
dodatečná záhlaví	Další hlavičky požadavku HTTP.	Ne
časový limit požadavku HTTP	Č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 zápis dat. Výchozí hodnota je 00:01:40.	Ne
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].	Ne
typ komprese HTTP	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.	Ne
writeBatchSize	Počet záznamů pro zápis do jímky REST na dávku Výchozí hodnota je 1 0000.	Ne

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.

Ukázkový skript toku dat

Všimněte si použití transformace alter řádku před dřezem, která Data Factory instruuje, jaký typ akce má s vaším REST dřezem provést. Tou akcí může být vložení, aktualizace, upsertování nebo smazá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

Poznámka:

Tok dat při zpracování N stránek vygeneruje celkem volání rozhraní API N+1. To zahrnuje jedno počáteční volání pro odvození schématu a následná volání N odpovídající počtu stránek načtených ze zdroje.

Podpora stránkování

Když kopírujete data z REST API, REST API obvykle omezuje velikost payload odpovědi jednoho požadavku na rozumný počet. Pro vrácení velkého množství dat rozdělí výsledek do více stránek a vyžaduje, aby volající posílali po sobě jdoucí požadavky, aby získali další stránku výsledků. Obvykle je požadavek na jednu stránku dynamický a složený z informací vrácených v odpovědi na předchozí stránku.

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 jednu nebo více párů klíč-hodnota rozlišující písmena. Tato konfigurace se používá k generování požadavku začínajícího od druhé stránky. Konektor přestane iterovat, když dostane HTTP stavový kód 204 (No Content) nebo jakýkoli z JSONPath výrazů v vrací paginationRules null.

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

Klíč	Popis
absolutní URL	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 NEBO Záhlaví['request_header']	"request_header" je definovaný uživatelem, který odkazuje na jeden název hlavičky v dalším požadavku HTTP.
KonecPodmínka: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.
MaximálníPočetŽádostí	Určuje maximální číslo žádosti o stránkování. Nechejte ho prázdný, znamená to, že neexistuje žádný limit.
PodporaRFC5988	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 NEBO Hlavičky['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, protože odpověď ve formě pole objektů není podporována. 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 mapovacích datových tocích se liší od pravidel při kopírování v následujících ohledech:

1. Rozsah není podporován v mapování toků dat.
2. [''] není podporován v mapování toků dat. Místo toho použijte {} k úniku speciálního 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:
     Kopírovací aktivita: "EndCondition:$.data": "Prázdné"
     Mapování toků dat: EndCondition:body.data: "Empty"
   • Příklad 2:
     Kopírovací aktivita: "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:

nebo

Krok 2: Nastavte pravidla stránkování jako možnost 1 nebo 2:

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

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

Příklad 2: Proměnné v AbsoluteUrl

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

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

nebo

Krok 2: Nastavte pravidla stránkování na "AbsoluteUrl.{id}" :"RANGE:1:100:1".

Příklad 3: Proměnné v hlavičká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
Request 1: Header(id->0)
Request 2: Header(id->10)
......
Request 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".

Příklad 4: Proměnné jsou v AbsoluteUrl/QueryParameters/Headers, koncová proměnná není předdefinovaná a koncová podmínka je založena 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 se vyskytují 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 pravidla stránkování jako Example 1 a ponechte konec oblasti prázdný jako "AbsoluteUrl.{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: Paginace 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ž v odpovědi existuje hodnota konkrétního uzlu.

  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: Paginace končí, když hodnota hlavičkového klíče v odpovědi odpovídá uživatelsky definované hodnotě const

  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" ukončí stránkování, když hodnota hlavičkového klíče v odpovědi odpovídá 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: Nastavte koncovou podmínku tak, aby se vyhýbalo nekonečným požadavkům, když 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, kde je adresa URL další stránky reprezentována v 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: Nastavte pravidla stránkování jako "AbsoluteUrl": "$.paging.next".

Krok 2: Pokud next je v poslední odpovědi vždy stejná jako URL posledního požadavku a není prázdná, proces posílá nekonečné množství požadavků. Použijte konečnou podmínku, abyste se vyhnuli nekonečným požadavkům. Proto nastavte pravidlo konečné podmínky odkazem na příklady 4.1 až 4.6.

Příklad 6: Nastavte maximální počet požadavků, abyste se vyhnuli nekonečnému počtu požadavků

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

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

Backend automaticky získá další URL na základě odkazů ve stylu RFC 5988 v hlavičce.

Návod

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

Příklad 8a: Adresa URL dalšího požadavku je v 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:

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

Ve výchozím nastavení stránkování přestane, když body.{@odata.nextLink} je nulová nebo prázdná.

Pokud však hodnota @odata.nextLink v těle poslední odpovědi odpovídá URL posledního požadavku, vede to k nekonečnému cyklu. 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 8b: Adresa URL dalšího požadavku je v textu odpovědi při použití stránkování v aktivitě kopírování.

Tento příklad ukazuje, jak nastavit pravidlo stránkování v aktivitě kopírování, když je adresa URL dalšího požadavku obsažena v textu odpovědi.

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

Pravidla stránkování by měla být nastavená, jak je znázorněno na následujícím snímku obrazovky:

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 vidět na následujícím screenshotu, první URL je https://< user.dfs.core.windows.net/bugfix/test/movie_1.xml>

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

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:

Export odpovědi JSON tak, jak je

Pomocí konektoru REST můžete exportovat odpověď JSON rozhraní REST API as-is do různých úložných systémů. Pro umožnění tohoto chování nezávislého na schématu použijte výchozí mapování schématu (nedefinujte žádné mapování v záložce Copy Activity).

Mapování schémat

Pokud chcete kopírovat data z REST koncového bodu do tabulkového úložiště, podívejte se na mapování schématu.

Související obsah

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