Kopiera och transformera data från och till en REST-slutpunkt med Azure Data Factory

Artikel
10/16/2024

GÄLLER FÖR: Azure Data Factory Azure Synapse Analytics

Dricks

Prova Data Factory i Microsoft Fabric, en allt-i-ett-analyslösning för företag. Microsoft Fabric omfattar allt från dataflytt till datavetenskap, realtidsanalys, business intelligence och rapportering. Lär dig hur du startar en ny utvärderingsversion kostnadsfritt!

I den här artikeln beskrivs hur du använder kopieringsaktiviteten i Azure Data Factory från och till en REST-slutpunkt. Artikeln bygger på Kopieringsaktivitet i Azure Data Factory som visar en allmän översikt över kopieringsaktivitet.

Skillnaden mellan den här REST-anslutningsprogram, HTTP-anslutningsprogram och webbtabell-anslutningsprogram är:

REST-anslutningsprogrammet stöder specifikt kopiering av data från RESTful-API:er.
HTTP-anslutningsprogrammet är allmän för att hämta data från en HTTP-slutpunkt, till exempel för att ladda ned filen. Innan det här REST-anslutningsprogrammet kan du använda HTTP-anslutningsprogrammet för att kopiera data från RESTful-API:er, vilket stöds men är mindre funktionellt jämfört med REST-anslutningsprogrammet.
Webbtabell-anslutningsprogram extraherar tabellinnehåll från en HTML-webbsida.

Funktioner som stöds

Den här REST-anslutningsappen stöds för följande funktioner:

Funktioner som stöds	IR
aktiviteten Kopiera (källa/mottagare)	(1) (2)
Mappa dataflöde (källa/mottagare)	(1)

(1) Azure Integration Runtime (2) Lokalt installerad integrationskörning

En lista över datalager som stöds som källor/mottagare finns i Datalager som stöds.

Mer specifikt stöder den här allmänna REST-anslutningsappen:

Kopiera data från en REST-slutpunkt med hjälp av GET - eller POST-metoderna och kopiera data till en REST-slutpunkt med hjälp av METODERNA POST, PUT eller PATCH .
Kopiera data med någon av följande autentiseringar: Anonymous, Basic, Service Principal, OAuth2 Client Credential, System Assigned Managed Identity och User Assigned Managed Identity.
Sidnumrering i REST-API:erna.
För REST som källa kopierar du REST JSON-svaret som det är eller parsar det med hjälp av schemamappning. Endast svarsnyttolast i JSON stöds.

Dricks

Om du vill testa en begäran om datahämtning innan du konfigurerar REST-anslutningsappen i Data Factory kan du läsa mer om API-specifikationen för krav på sidhuvud och brödtext. Du kan använda verktyg som Visual Studio, PowerShells Invoke-RestMethod eller en webbläsare för att verifiera.

Förutsättningar

Om ditt datalager finns i ett lokalt nätverk, ett virtuellt Azure-nätverk eller Amazon Virtual Private Cloud måste du konfigurera en lokalt installerad integrationskörning för att ansluta till det.

Om ditt datalager är en hanterad molndatatjänst kan du använda Azure Integration Runtime. Om åtkomsten är begränsad till IP-adresser som är godkända i brandväggsreglerna kan du lägga till Azure Integration Runtime-IP-adresser i listan över tillåtna.

Du kan också använda funktionen för integrering av hanterade virtuella nätverk i Azure Data Factory för att få åtkomst till det lokala nätverket utan att installera och konfigurera en lokalt installerad integrationskörning.

Mer information om de nätverkssäkerhetsmekanismer och alternativ som stöds av Data Factory finns i Strategier för dataåtkomst.

Kom igång

Om du vill utföra aktiviteten Kopiera med en pipeline kan du använda något av följande verktyg eller SDK:er:

Skapa en REST-länkad tjänst med hjälp av användargränssnittet

Använd följande steg för att skapa en REST-länkad tjänst i Azure Portal användargränssnittet.

Bläddra till fliken Hantera i Din Azure Data Factory- eller Synapse-arbetsyta och välj Länkade tjänster och välj sedan Nytt:
- Azure Data Factory
- Azure Synapse
Sök efter REST och välj REST-anslutningsappen.
Konfigurera tjänstinformationen, testa anslutningen och skapa den nya länkade tjänsten.

Konfigurationsinformation för anslutningsprogram

Följande avsnitt innehåller information om egenskaper som du kan använda för att definiera Data Factory-entiteter som är specifika för REST-anslutningsappen.

Länkade tjänstegenskaper

Följande egenskaper stöds för den REST-länkade tjänsten:

Property	Beskrivning	Obligatoriskt
type	Typegenskapen måste vara inställd på RestService.	Ja
URL	REST-tjänstens bas-URL.	Ja
enableServerCertificateValidation	Om du vill verifiera TLS/SSL-certifikat på serversidan när du ansluter till slutpunkten.	Nej (standardvärdet är sant)
authenticationType	Typ av autentisering som används för att ansluta till REST-tjänsten. Tillåtna värden är Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential och ManagedServiceIdentity. Du kan dessutom konfigurera autentiseringshuvuden i `authHeaders` egenskapen . Se motsvarande avsnitt nedan om fler egenskaper respektive exempel.	Ja
authHeaders	Ytterligare HTTP-begärandehuvuden för autentisering. Om du till exempel vill använda API-nyckelautentisering kan du välja autentiseringstyp som "Anonym" och ange API-nyckel i rubriken.	Nej
connectVia	Integration Runtime som ska användas för att ansluta till datalagret. Läs mer i avsnittet Förutsättningar . Om den inte anges använder den här egenskapen standardkörningen för Azure-integrering.	Nej

Information om olika autentiseringstyper finns i motsvarande avsnitt.

Grundläggande autentisering
Autentisering med tjänstens huvudnamn
Autentisering med OAuth2-klientautentiseringsuppgifter
Systemtilldelad autentisering av hanterad identitet
Användartilldelad hanterad identitetsautentisering
Anonym autentisering

Använda grundläggande autentisering

Ange egenskapen authenticationType till Basic. Förutom de allmänna egenskaper som beskrivs i föregående avsnitt anger du följande egenskaper:

Property	Beskrivning	Obligatoriskt
userName	Användarnamnet som ska användas för att komma åt REST-slutpunkten.	Ja
password	Lösenordet för användaren ( värdet userName ). Markera det här fältet som en SecureString-typ för att lagra det på ett säkert sätt i Data Factory. Du kan också referera till en hemlighet som lagras i Azure Key Vault.	Ja

Exempel

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

Använda autentisering med tjänstens huvudnamn

Ange egenskapen authenticationType till AadServicePrincipal. Förutom de allmänna egenskaper som beskrivs i föregående avsnitt anger du följande egenskaper:

Property	Beskrivning	Obligatoriskt
servicePrincipalId	Ange Microsoft Entra-programmets klient-ID.	Ja
servicePrincipalCredentialType	Ange vilken typ av autentiseringsuppgifter som ska användas för autentisering med tjänstens huvudnamn. Tillåtna värden är `ServicePrincipalKey` och `ServicePrincipalCert`.	Nej
För ServicePrincipalKey
servicePrincipalKey	Ange Microsoft Entra-programmets nyckel. Markera det här fältet som en SecureString för att lagra det på ett säkert sätt i Data Factory eller referera till en hemlighet som lagras i Azure Key Vault.	Nej
För ServicePrincipalCert
servicePrincipalEmbeddedCert	Ange det base64-kodade certifikatet för ditt program som är registrerat i Microsoft Entra-ID och se till att certifikatinnehållstypen är PKCS #12. Markera det här fältet som en SecureString för att lagra det på ett säkert sätt eller referera till en hemlighet som lagras i Azure Key Vault. Gå till det här avsnittet om du vill lära dig hur du sparar certifikatet i Azure Key Vault.	Nej
servicePrincipalEmbeddedCertPassword	Ange lösenordet för certifikatet om certifikatet skyddas med ett lösenord. Markera det här fältet som en SecureString för att lagra det på ett säkert sätt eller referera till en hemlighet som lagras i Azure Key Vault.	Nej

klientorganisation	Ange klientinformationen (domännamn eller klient-ID) som programmet finns under. Hämta den genom att hovra musen i det övre högra hörnet av Azure Portal.	Ja
aadResourceId	Ange den Microsoft Entra-resurs som du begär för auktorisering, `https://management.core.windows.net`till exempel .	Ja
azureCloudType	För autentisering med tjänstens huvudnamn anger du vilken typ av Azure-molnmiljö som ditt Microsoft Entra-program är registrerat i. Tillåtna värden är AzurePublic, AzureChina, AzureUsGovernment och AzureGermany. Som standard används datafabrikens molnmiljö.	Nej

Exempel 1: Använda nyckelautentisering för tjänstens huvudnamn

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

Exempel 2: Använda certifikatautentisering med tjänstens huvudnamn

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

Spara certifikatet för tjänstens huvudnamn i Azure Key Vault

Du har två alternativ för att spara certifikatet för tjänstens huvudnamn i Azure Key Vault:

Alternativ 1
1. Konvertera certifikatet för tjänstens huvudnamn till en base64-sträng. Läs mer i den här artikeln.
2. Spara base64-strängen som en hemlighet i Azure Key Vault.
Alternativ 2

Om du inte kan ladda ned certifikatet från Azure Key Vault kan du använda den här mallen för att spara det konverterade certifikatet för tjänstens huvudnamn som en hemlighet i Azure Key Vault.

Använda autentisering med OAuth2-klientautentiseringsuppgifter

Ange egenskapen authenticationType till OAuth2ClientCredential. Förutom de allmänna egenskaper som beskrivs i föregående avsnitt anger du följande egenskaper:

Property	Beskrivning	Obligatoriskt
tokenEndpoint	Tokenslutpunkten för auktoriseringsservern för att hämta åtkomsttoken.	Ja
clientId	Klient-ID:t som är associerat med ditt program.	Ja
clientSecret	Klienthemligheten som är associerad med ditt program. Markera det här fältet som en SecureString-typ för att lagra det på ett säkert sätt i Data Factory. Du kan också referera till en hemlighet som lagras i Azure Key Vault.	Ja
omfattning	Omfånget för den åtkomst som krävs. Den beskriver vilken typ av åtkomst som kommer att begäras.	Nej
resource	Den måltjänst eller resurs som åtkomsten ska begäras till.	Nej

Exempel

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

Använda systemtilldelad hanterad identitetsautentisering

Ange egenskapen authenticationType till ManagedServiceIdentity. Förutom de allmänna egenskaper som beskrivs i föregående avsnitt anger du följande egenskaper:

Property	Beskrivning	Obligatoriskt
aadResourceId	Ange den Microsoft Entra-resurs som du begär för auktorisering, `https://management.core.windows.net`till exempel .	Ja

Exempel

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

Använda användartilldelad hanterad identitetsautentisering

Ange egenskapen authenticationType till ManagedServiceIdentity. Förutom de allmänna egenskaper som beskrivs i föregående avsnitt anger du följande egenskaper:

Property	Beskrivning	Obligatoriskt
aadResourceId	Ange den Microsoft Entra-resurs som du begär för auktorisering, `https://management.core.windows.net`till exempel .	Ja
autentiseringsuppgifter	Ange den användartilldelade hanterade identiteten som autentiseringsobjekt.	Ja

Exempel

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

Använda autentiseringshuvuden

Dessutom kan du konfigurera begärandehuvuden för autentisering tillsammans med de inbyggda autentiseringstyperna.

Exempel: Använda API-nyckelautentisering

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

Egenskaper för datauppsättning

Det här avsnittet innehåller en lista över egenskaper som REST-datauppsättningen stöder.

En fullständig lista över avsnitt och egenskaper som är tillgängliga för att definiera datauppsättningar finns i Datauppsättningar och länkade tjänster.

Följande egenskaper stöds för att kopiera data från REST:

Property	Beskrivning	Obligatoriskt
type	Datamängdens typegenskap måste anges till RestResource.	Ja
relativeUrl	En relativ URL till resursen som innehåller data. När den här egenskapen inte har angetts används endast den URL som anges i den länkade tjänstdefinitionen. HTTP-anslutningsappen kopierar data från den kombinerade URL:en: `[URL specified in linked service]/[relative URL specified in dataset]`.	Nej

Om du ställer in requestMethod, additionalHeadersrequestBody och paginationRules i datauppsättningen stöds den fortfarande som den är, medan du rekommenderas att använda den nya modellen i aktiviteten framöver.

Exempel:

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

Egenskaper för kopieringsaktivitet

Det här avsnittet innehåller en lista över egenskaper som stöds av REST-källan och mottagaren.

En fullständig lista över avsnitt och egenskaper som är tillgängliga för att definiera aktiviteter finns i Pipelines.

REST som källa

Följande egenskaper stöds i avsnittet kopieringsaktivitetskälla:

Property	Beskrivning	Obligatoriskt
type	Typegenskapen för kopieringsaktivitetskällan måste anges till RestSource.	Ja
requestMethod	HTTP-metoden. Tillåtna värden är GET (standard) och POST.	Nej
additionalHeaders	Ytterligare HTTP-begärandehuvuden.	Nej
requestBody	Brödtexten för HTTP-begäran.	Nej
paginationRules	Sidnumreringsreglerna för att skapa nästa sidbegäranden. Mer information finns i avsnittet om sidnumreringsstöd.	Nej
httpRequestTimeout	Tidsgränsen (TimeSpan-värdet ) för HTTP-begäran för att få ett svar. Det här värdet är tidsgränsen för att få ett svar, inte tidsgränsen för att läsa svarsdata. Standardvärdet är 00:01:40.	Nej
requestInterval	Tiden att vänta innan begäran skickas till nästa sida. Standardvärdet är 00:00:01	Nej

Kommentar

REST-anslutningsappen ignorerar alla "Acceptera"-huvuden som anges i additionalHeaders. Eftersom REST-anslutningsappen endast stöder svar i JSON genereras automatiskt en rubrik på Accept: application/json.
Matrisen med objektet som svarstext stöds inte i sidnumrering.

Exempel 1: Använda metoden Hämta med sidnumrering

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

Exempel 2: Använda postmetoden

"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 som mottagare

Följande egenskaper stöds i avsnittet kopieringsaktivitetsmottagare:

Property	Beskrivning	Obligatoriskt
type	Typegenskapen för kopieringsaktivitetsmottagaren måste anges till RestSink.	Ja
requestMethod	HTTP-metoden. Tillåtna värden är POST (standard), PUT och PATCH.	Nej
additionalHeaders	Ytterligare HTTP-begärandehuvuden.	Nej
httpRequestTimeout	Tidsgränsen (TimeSpan-värdet ) för HTTP-begäran för att få ett svar. Det här värdet är tidsgränsen för att få ett svar, inte tidsgränsen för att skriva data. Standardvärdet är 00:01:40.	Nej
requestInterval	Intervalltiden mellan olika begäranden i millisekunder. Värdet för begärandeintervallet ska vara ett tal mellan [10, 60000].	Nej
httpCompressionType	HTTP-komprimeringstyp som ska användas när data skickas med optimal komprimeringsnivå. Tillåtna värden är ingen och gzip.	Nej
writeBatchSize	Antal poster som ska skrivas till REST-mottagaren per batch. Standardvärdet är 10000.	Nej

REST-anslutningsappen som mottagare fungerar med REST-API:er som accepterar JSON. Data skickas i JSON med följande mönster. Vid behov kan du använda schemamappningen för kopieringsaktivitet för att omforma källdata så att de överensstämmer med den förväntade nyttolasten i REST-API:et.

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

Exempel:

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

Mappa dataflödesegenskaper

REST stöds i dataflöden för både integreringsdatauppsättningar och infogade datauppsättningar.

Källtransformering

Property	Beskrivning	Obligatoriskt
requestMethod	HTTP-metoden. Tillåtna värden är GET och POST.	Ja
relativeUrl	En relativ URL till resursen som innehåller data. När den här egenskapen inte har angetts används endast den URL som anges i den länkade tjänstdefinitionen. HTTP-anslutningsappen kopierar data från den kombinerade URL:en: `[URL specified in linked service]/[relative URL specified in dataset]`.	Nej
additionalHeaders	Ytterligare HTTP-begärandehuvuden.	Nej
httpRequestTimeout	Tidsgränsen (TimeSpan-värdet ) för HTTP-begäran för att få ett svar. Det här värdet är tidsgränsen för att få ett svar, inte tidsgränsen för att skriva data. Standardvärdet är 00:01:40.	Nej
requestInterval	Intervalltiden mellan olika begäranden i millisekunder. Värdet för begärandeintervallet ska vara ett tal mellan [10, 60000].	Nej
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter']	"request_query_parameter" är användardefinierad, vilket refererar till ett frågeparameternamn i nästa URL för HTTP-begäran.	Nej

Transformering av mottagare

Property	Beskrivning	Obligatoriskt
additionalHeaders	Ytterligare HTTP-begärandehuvuden.	Nej
httpRequestTimeout	Tidsgränsen (TimeSpan-värdet ) för HTTP-begäran för att få ett svar. Det här värdet är tidsgränsen för att få ett svar, inte tidsgränsen för att skriva data. Standardvärdet är 00:01:40.	Nej
requestInterval	Intervalltiden mellan olika begäranden i millisekunder. Värdet för begärandeintervallet ska vara ett tal mellan [10, 60000].	Nej
httpCompressionType	HTTP-komprimeringstyp som ska användas när data skickas med optimal komprimeringsnivå. Tillåtna värden är ingen och gzip.	Nej
writeBatchSize	Antal poster som ska skrivas till REST-mottagaren per batch. Standardvärdet är 10000.	Nej

Du kan ange metoderna delete, insert, update och upsert samt de relativa raddata som ska skickas till REST-mottagaren för CRUD-åtgärder.

REST-mottagare för dataflöde

Exempel på dataflödesskript

Observera användningen av en ändringsradtransformering före mottagaren för att instruera ADF vilken typ av åtgärd som ska vidtas med DIN REST-mottagare. Dvs. infoga, uppdatera, upsert, ta bort.

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

Sidnumreringssupport

När du kopierar data från REST-API:er begränsar rest-API:et normalt sin svarsnyttolaststorlek för en enskild begäran under ett rimligt antal. för att returnera stora mängder data delar det upp resultatet i flera sidor och kräver att anropare skickar på varandra följande begäranden för att få nästa sida i resultatet. Vanligtvis är begäran om en sida dynamisk och består av den information som returneras från svaret från föregående sida.

Den här allmänna REST-anslutningsappen stöder följande sidnumreringsmönster:

Nästa begärans absoluta eller relativa URL = egenskapsvärde i den aktuella svarstexten
Nästa begärans absoluta eller relativa URL = rubrikvärde i aktuella svarshuvuden
Frågeparametern för nästa begäran = egenskapsvärdet i den aktuella svarstexten
Nästa begärans frågeparameter = rubrikvärde i aktuella svarshuvuden
Nästa begärans huvud = egenskapsvärde i aktuell svarstext
Nästa begärans sidhuvud = rubrikvärde i aktuella svarshuvuden

Sidnumreringsregler definieras som en ordlista i datauppsättningen, som innehåller ett eller flera skiftlägeskänsliga nyckel/värde-par. Konfigurationen används för att generera begäran från och med den andra sidan. Anslutningsappen slutar iterera när den hämtar HTTP-statuskod 204 (inget innehåll) eller något av JSONPath-uttrycken i "paginationRules" returnerar null.

Nycklar som stöds i sidnumreringsregler:

Nyckel	beskrivning
AbsoluteUrl	Anger url:en för att utfärda nästa begäran. Det kan vara antingen absolut URL eller relativ URL.
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter']	"request_query_parameter" är användardefinierad, vilket refererar till ett frågeparameternamn i nästa URL för HTTP-begäran.
Headers. request_header ELLER-huvuden['request_header']	"request_header" är användardefinierad, vilket refererar till ett huvudnamn i nästa HTTP-begäran.
EndCondition:end_condition	"end_condition" är användardefinierad, vilket anger villkoret som avslutar sidnumreringsloopen i nästa HTTP-begäran.
MaxRequestNumber	Anger det maximala antalet sidnumreringsbegäranden. Lämna den som tom innebär ingen gräns.
SupportRFC5988	Som standard är detta inställt på sant om ingen sidnumreringsregel har definierats. Du kan inaktivera den här regeln genom att ange `supportRFC5988` false eller ta bort den här egenskapen från skriptet.

Värden som stöds i sidnumreringsregler:

Värde	beskrivning
Headers. response_header ELLER-huvuden['response_header']	"response_header" är användardefinierad, som refererar till ett huvudnamn i det aktuella HTTP-svaret, vars värde kommer att användas för att utfärda nästa begäran.
Ett JSONPath-uttryck som börjar med "$" (som representerar roten i svarstexten)	Svarstexten ska bara innehålla ett JSON-objekt och matrisen för objektet eftersom svarstexten inte stöds. JSONPath-uttrycket ska returnera ett enda primitivt värde som används för att utfärda nästa begäran.

Kommentar

Sidnumreringsreglerna i mappningen av dataflöden skiljer sig från dem i kopieringsaktiviteten i följande aspekter:

Intervall stöds inte i mappning av dataflöden.
[''] stöds inte i mappning av dataflöden. Använd {} i stället för att undkomma specialtecken. Till exempel , body.{@odata.nextLink}vars JSON-nod @odata.nextLink innehåller specialtecken . .
Slutvillkoret stöds i mappning av dataflöden, men villkorssyntaxen skiljer sig från den i kopieringsaktiviteten. body används för att ange svarstexten i stället för $. header används för att ange svarshuvudet i stället för headers. Här är två exempel som visar den här skillnaden:
- Exempel 1:
  aktiviteten Kopiera: "EndCondition:$.data": "Empty"
  Mappa dataflöden: "EndCondition:body.data": "Tom"
- Exempel 2:
  aktiviteten Kopiera: "EndCondition:headers.complete": "Exist"
  Mappa dataflöden: "EndCondition:header.complete": "Exist"

Exempel på sidnumreringsregler

Det här avsnittet innehåller en lista med exempel på inställningar för sidnumreringsregler.

Exempel 1: Variabler i QueryParameters

Det här exemplet innehåller konfigurationsstegen för att skicka flera begäranden vars variabler finns i QueryParameters.

Flera begäranden:

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

Steg 1: Ange sysparm_offset={offset} antingen i bas-URL eller relativ URL enligt följande skärmbilder:

Skärmbild som visar en konfiguration för att skicka flera begäranden vars variabler finns i Frågeparametrar.

eller

Skärmbild som visar en annan konfiguration för att skicka flera begäranden vars variabler finns i Frågeparametrar.

Steg 2: Ange sidnumreringsregler som alternativ 1 eller alternativ 2:

Alternativ 1: "QueryParameters.{ offset}" : "RANGE:0:10000:1000"
Alternativ 2: "AbsoluteUrl.{ offset}" : "RANGE:0:10000:1000"

Exempel 2:Variabler i AbsoluteUrl

Det här exemplet innehåller konfigurationsstegen för att skicka flera begäranden vars variabler finns i AbsoluteUrl.

Flera begäranden:

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

Steg 1: Ange {id} antingen i bas-URL:en på konfigurationssidan för den länkade tjänsten eller relativ URL i fönstret för datauppsättningsanslutning.

Skärmbild som visar en konfiguration för att skicka flera begäranden vars variabler finns i Absolut URL.

eller

Skärmbild som visar en annan konfiguration för att skicka flera begäranden vars variabler finns i Absolut URL.

Steg 2: Ange sidnumreringsregler som "AbsoluteUrl.{ id}" :"RANGE:1:100:1".

Exempel 3:Variabler i rubriker

Det här exemplet innehåller konfigurationsstegen för att skicka flera begäranden vars variabler finns i Rubriker.

Flera begäranden:
RequestUrl: https://example/table
Begäran 1: Header(id->0)
Begäran 2: Header(id->10)
......
Begäran 100: Header(id->100)

Steg 1: Indata {id} i Ytterligare rubriker.

Steg 2: Ange sidnumreringsregler som "Rubriker.{ id}" : "RANGE:0:100:10".

Skärmbild som visar sidnumreringsregeln för att skicka flera begäranden vars variabler finns i Rubriker.

Exempel 4:Variabler finns i AbsoluteUrl/QueryParameters/Headers, slutvariabeln är inte fördefinierad och slutvillkoret baseras på svaret

Det här exemplet innehåller konfigurationssteg för att skicka flera begäranden vars variabler finns i AbsoluteUrl/QueryParameters/Headers men slutvariabeln har inte definierats. För olika svar visas olika regelinställningar för slutvillkor i exempel 4.1-4.6.

Flera begäranden:

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

Två svar påträffades i det här exemplet:

Svar 1:

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

Svar 2:

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

Steg 1: Ange intervallet för sidnumreringsregler som Exempel 1 och låt slutet av intervallet vara tomt som "AbsoluteUrl.{ offset}": "RANGE:0::1000".

Steg 2: Ange olika regler för slutvillkor enligt olika senaste svar. Se exempel nedan:

Exempel 4.1: Sidnumreringen slutar när värdet för den specifika noden i svaret är tomt

REST-API:et returnerar det sista svaret i följande struktur:
```
{
    Data: []
}
```
Ange slutvillkorsregeln som "EndCondition:$.data": "Tom" för att avsluta sidnumreringen när värdet för den specifika noden som svar är tomt.
Exempel 4.2: Sidnumreringen slutar när värdet för den specifika noden som svar inte finns

REST-API:et returnerar det sista svaret i följande struktur:
```
{}
```
Ange slutvillkorsregeln som "EndCondition:$.data": "NonExist" för att avsluta sidnumreringen när värdet för den specifika noden som svar inte finns.
Exempel 4.3: Sidnumreringen slutar när värdet för den specifika noden i svaret finns

REST-API:et returnerar det sista svaret i följande struktur:
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
Ange slutvillkorsregeln som "EndCondition:$. Slutförd: "Finns" för att avsluta sidnumreringen när värdet för den specifika noden som svar finns.
Exempel 4.4: Sidnumreringen upphör när värdet för den specifika noden som svar är ett användardefinierat const-värde

REST-API:et returnerar svaret i följande struktur:
```
{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}
```
......

Och det sista svaret finns i följande struktur:
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
Ange slutvillkorsregeln som "EndCondition:$. Slutförd: "Const:true" för att avsluta sidnumreringen när värdet för den specifika noden som svar är ett användardefinierat const-värde.
Exempel 4.5: Sidnumreringen slutar när värdet för huvudnyckeln som svar är lika med användardefinierat const-värde

Huvudnycklarna i REST API-svar visas i strukturen nedan:

Svarsrubrik 1: header(Complete->0)
......
Senaste svarsrubrik: header(Complete->1)

Ange slutvillkorsregeln som "EndCondition:headers. Slutförd: "Const:1" för att avsluta sidnumreringen när värdet för huvudnyckeln som svar är lika med användardefinierade const-värde.
Exempel 4.6: Sidnumreringen slutar när nyckeln finns i svarshuvudet

Huvudnycklarna i REST API-svar visas i strukturen nedan:

Svarsrubrik 1: header()
......
Senaste svarsrubrik: header(CompleteTime->20220920)

Ange slutvillkorsregeln som "EndCondition:headers. CompleteTime": "Finns" för att avsluta sidnumreringen när nyckeln finns i svarshuvudet.

Exempel 5:Ange slutvillkor för att undvika oändliga begäranden när intervallregeln inte har definierats

Det här exemplet innehåller konfigurationsstegen för att skicka flera begäranden när intervallregeln inte används. Slutvillkoret kan anges i exempel 4.1-4.6 för att undvika oändliga begäranden. REST-API:et returnerar svar i följande struktur, i vilket fall nästa sidas URL representeras i växling.nästa.

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

Det sista svaret är:

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

Steg 1: Ange sidnumreringsregler som "AbsoluteUrl": "$.paging.next".

Steg 2: Om next i det senaste svaret alltid är detsamma med den senaste begärande-URL:en och inte tom skickas oändliga begäranden. Slutvillkoret kan användas för att undvika oändliga begäranden. Ange därför slutvillkorsregeln i Exempel 4.1-4.6.

Exempel 6:Ange maximalt antal begäranden för att undvika oändliga förfrågningar

Ange MaxRequestNumber för att undvika oändliga begäranden enligt följande skärmbild:

Skärmbild som visar inställningen Maximalt antal begäranden för exempel 6.

Exempel 7:RFC 5988-sidnumreringsregeln stöds som standard

Serverdelen får automatiskt nästa URL baserat på RFC 5988-formatlänkarna i rubriken.

Skärmbild som visar exempel på http-huvudet som uppfyller R F C 5988.

Dricks

Om du inte vill aktivera den här standardregeln för sidnumrering kan du ange supportRFC5988 till false eller bara ta bort den i skriptet.

Skärmbild som visar hur du inaktiverar R F C 5988-inställningen för Exempel 7.

Exempel 8: Nästa begärande-URL kommer från svarstexten när sidnumrering används i mappning av dataflöden

Det här exemplet anger hur du anger sidnumreringsregeln och regeln för slutvillkor i mappningen av dataflöden när nästa begärans URL kommer från svarstexten.

Svarsschemat visas nedan:

Skärmbild som visar svarsschemat för exempel 8.

Sidnumreringsreglerna ska anges som följande skärmbild:

Skärmbild som visar hur du anger sidnumreringsregeln för Exempel 8.

Som standard stoppas sidnumreringen när brödtexten används. {@odata.nextLink}** är null eller tomt.

Men om värdet för @odata.nextLink i den sista svarstexten är lika med den senaste begärande-URL:en leder det till den oändliga loopen. För att undvika det här villkoret definierar du regler för slutvillkor.

Om Värdet i det senaste svaret är Tomt kan regeln för slutvillkor anges enligt nedan:
Om värdet för den fullständiga nyckeln i svarshuvudet är lika med sant anger slutet av sidnumreringen, kan regeln för slutvillkor anges enligt nedan:

Exempel 9: Svarsformatet är XML och nästa begärande-URL kommer från svarstexten när sidnumrering används i mappning av dataflöden

Det här exemplet anger hur du anger sidnumreringsregeln i mappning av dataflöden när svarsformatet är XML och nästa begärande-URL kommer från svarstexten. Som du ser i följande skärmbild är den första URL:en https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

Skärmbild som visar svarsformatet är X M L och nästa begäran U R L kommer från svarstexten.

Svarsschemat visas nedan:

Skärmbild som visar svarsschemat för exempel 9.

Syntaxen för sidnumreringsregeln är densamma som i Exempel 8 och bör anges som nedan i det här exemplet:

Skärmbild som visar hur du anger sidnumreringsregeln för Exempel 9.

Exportera JSON-svar som det är

Du kan använda den här REST-anslutningsappen för att exportera REST API JSON-svar som det är till olika filbaserade arkiv. Om du vill uppnå en sådan schemaagnostisk kopia hoppar du över avsnittet "struktur" (kallas även schema) i datauppsättningen och schemamappningen i kopieringsaktiviteten.

Schemamappning

Om du vill kopiera data från REST-slutpunkten till tabellmottagaren läser du schemamappning.

En lista över datalager som kopieringsaktivitet stöder som källor och mottagare i Azure Data Factory finns i Datalager och format som stöds.

Dela via

Kopiera och transformera data från och till en REST-slutpunkt med Azure Data Factory

Funktioner som stöds

Förutsättningar

Kom igång

Skapa en REST-länkad tjänst med hjälp av användargränssnittet

Konfigurationsinformation för anslutningsprogram

Länkade tjänstegenskaper

Använda grundläggande autentisering

Använda autentisering med tjänstens huvudnamn

Spara certifikatet för tjänstens huvudnamn i Azure Key Vault

Använda autentisering med OAuth2-klientautentiseringsuppgifter

Använda systemtilldelad hanterad identitetsautentisering

Använda användartilldelad hanterad identitetsautentisering

Använda autentiseringshuvuden

Egenskaper för datauppsättning

Egenskaper för kopieringsaktivitet

REST som källa

REST som mottagare

Mappa dataflödesegenskaper

Källtransformering

Transformering av mottagare

Exempel på dataflödesskript

Exempel 1: Variabler i QueryParameters

Exempel 2:Variabler i AbsoluteUrl

Exempel 3:Variabler i rubriker

Exempel 4:Variabler finns i AbsoluteUrl/QueryParameters/Headers, slutvariabeln är inte fördefinierad och slutvillkoret baseras på svaret

Exempel 5:Ange slutvillkor för att undvika oändliga begäranden när intervallregeln inte har definierats

Exempel 6:Ange maximalt antal begäranden för att undvika oändliga förfrågningar

Exportera JSON-svar som det är

Schemamappning

Feedback

Ytterligare resurser

Dela via

Kopiera och transformera data från och till en REST-slutpunkt med Azure Data Factory

Funktioner som stöds

Förutsättningar

Kom igång

Skapa en REST-länkad tjänst med hjälp av användargränssnittet

Konfigurationsinformation för anslutningsprogram

Länkade tjänstegenskaper

Använda grundläggande autentisering

Använda autentisering med tjänstens huvudnamn

Spara certifikatet för tjänstens huvudnamn i Azure Key Vault

Använda autentisering med OAuth2-klientautentiseringsuppgifter

Använda systemtilldelad hanterad identitetsautentisering

Använda användartilldelad hanterad identitetsautentisering

Använda autentiseringshuvuden

Egenskaper för datauppsättning

Egenskaper för kopieringsaktivitet

REST som källa

REST som mottagare

Mappa dataflödesegenskaper

Källtransformering

Transformering av mottagare

Exempel på dataflödesskript

Sidnumreringssupport

Exempel på sidnumreringsregler

Exempel 1: Variabler i QueryParameters

Exempel 2:Variabler i AbsoluteUrl

Exempel 3:Variabler i rubriker

Exempel 4:Variabler finns i AbsoluteUrl/QueryParameters/Headers, slutvariabeln är inte fördefinierad och slutvillkoret baseras på svaret

Exempel 5:Ange slutvillkor för att undvika oändliga begäranden när intervallregeln inte har definierats

Exempel 6:Ange maximalt antal begäranden för att undvika oändliga förfrågningar

Exempel 7:RFC 5988-sidnumreringsregeln stöds som standard

Exempel 8: Nästa begärande-URL kommer från svarstexten när sidnumrering används i mappning av dataflöden

Exempel 9: Svarsformatet är XML och nästa begärande-URL kommer från svarstexten när sidnumrering används i mappning av dataflöden

Exportera JSON-svar som det är

Schemamappning

Relaterat innehåll

Feedback

Ytterligare resurser