Share via

Gegevens kopiëren en transformeren van en naar een REST-eindpunt met behulp van Azure Data Factory

  • Artikel

VAN TOEPASSING OP: Azure Data Factory Azure Synapse Analytics

Tip

Probeer Data Factory uit in Microsoft Fabric, een alles-in-één analyseoplossing voor ondernemingen. Microsoft Fabric omvat alles, van gegevensverplaatsing tot gegevenswetenschap, realtime analyses, business intelligence en rapportage. Meer informatie over het gratis starten van een nieuwe proefversie .

In dit artikel wordt beschreven hoe u de kopieeractiviteit in Azure Data Factory kunt gebruiken om gegevens van een naar een REST-eindpunt te kopiëren. Het artikel bouwt voort op Kopieeractiviteit in Azure Data Factory, waarin een algemeen overzicht van Copy-activiteit wordt weergegeven.

De verschillen tussen deze REST-connector, HTTP-connector en de webtabelconnector zijn:

  • REST-connector biedt specifiek ondersteuning voor het kopiëren van gegevens uit RESTful-API's.
  • HTTP-connector is algemeen om gegevens op te halen van een HTTP-eindpunt, bijvoorbeeld om een bestand te downloaden. Voordat u deze REST-connector gebruikt, kunt u HTTP-connector gebruiken om gegevens te kopiëren van RESTful-API's, die wel worden ondersteund, maar minder functioneel zijn dan de REST-connector.
  • Webtabelconnector extraheert tabelinhoud uit een HTML-webpagina.

Ondersteunde mogelijkheden

Deze REST-connector wordt ondersteund voor de volgende mogelijkheden:

Ondersteunde mogelijkheden IR
Copy-activiteit (bron/sink) (1) (2)
Toewijzingsgegevensstroom (bron/sink) (1)

(1) Azure Integration Runtime (2) Zelf-hostende Integration Runtime

Zie Ondersteunde gegevensarchieven voor een lijst met gegevensarchieven die worden ondersteund als bronnen/sinks.

Deze algemene REST-connector ondersteunt met name:

  • Gegevens kopiëren van een REST-eindpunt met behulp van de GET- of POST-methoden en het kopiëren van gegevens naar een REST-eindpunt met behulp van de POST-, PUT- of PATCH-methoden.
  • Gegevens kopiëren met behulp van een van de volgende verificaties: Anoniem, Basic, Service Principal, OAuth2-clientreferenties, door het systeem toegewezen beheerde identiteit en door de gebruiker toegewezen beheerde identiteit.
  • Paginering in de REST API's.
  • Voor REST als bron kopieert u het REST JSON-antwoord as-is of parseert u het met behulp van schematoewijzing. Alleen nettolading van antwoorden in JSON wordt ondersteund.

Tip

Als u een aanvraag voor het ophalen van gegevens wilt testen voordat u de REST-connector in Data Factory configureert, leert u meer over de API-specificatie voor vereisten voor headers en hoofdteksten. U kunt hulpprogramma's zoals Postman of een webbrowser gebruiken om te valideren.

Vereisten

Als uw gegevensarchief zich in een on-premises netwerk, een virtueel Azure-netwerk of een virtuele particuliere cloud van Amazon bevindt, moet u een zelf-hostende Integration Runtime configureren om er verbinding mee te maken.

Als uw gegevensarchief een beheerde cloudgegevensservice is, kunt u De Azure Integration Runtime gebruiken. Als de toegang is beperkt tot IP-adressen die zijn goedgekeurd in de firewallregels, kunt u IP-adressen van Azure Integration Runtime toevoegen aan de acceptatielijst.

U kunt ook de beheerde functie voor integratieruntime voor virtuele netwerken in Azure Data Factory gebruiken om toegang te krijgen tot het on-premises netwerk zonder een zelf-hostende Integration Runtime te installeren en te configureren.

Zie Strategieën voor gegevenstoegang voor meer informatie over de netwerkbeveiligingsmechanismen en -opties die door Data Factory worden ondersteund.

Aan de slag

Als u de kopieeractiviteit wilt uitvoeren met een pijplijn, kunt u een van de volgende hulpprogramma's of SDK's gebruiken:

Een gekoppelde REST-service maken met behulp van de gebruikersinterface

Gebruik de volgende stappen om een gekoppelde REST-service te maken in de gebruikersinterface van Azure Portal.

  1. Blader naar het tabblad Beheren in uw Azure Data Factory- of Synapse-werkruimte en selecteer Gekoppelde services en selecteer vervolgens Nieuw:

  2. Zoek naar REST en selecteer de REST-connector.

    Select REST connector.

  3. Configureer de servicedetails, test de verbinding en maak de nieuwe gekoppelde service.

    Configure REST linked service.

configuratiedetails Verbinding maken or

De volgende secties bevatten details over eigenschappen die u kunt gebruiken om Data Factory-entiteiten te definiëren die specifiek zijn voor de REST-connector.

Eigenschappen van gekoppelde service

De volgende eigenschappen worden ondersteund voor de gekoppelde REST-service:

Eigenschappen Beschrijving Vereist
type De typeeigenschap moet worden ingesteld op RestService. Ja
URL De basis-URL van de REST-service. Ja
enableServerCertificateValidation Of u TLS/SSL-certificaat aan de serverzijde wilt valideren wanneer u verbinding maakt met het eindpunt. Nee
(de standaardwaarde is waar)
authenticationType Type verificatie dat wordt gebruikt om verbinding te maken met de REST-service. Toegestane waarden zijn Anoniem, Basic, AadServicePrincipal, OAuth2ClientCredential en ManagedServiceIdentity. U kunt ook verificatieheaders configureren in authHeaders de eigenschap. Raadpleeg de bijbehorende secties hieronder over respectievelijk meer eigenschappen en voorbeelden. Ja
authHeaders Aanvullende HTTP-aanvraagheaders voor verificatie.
Als u bijvoorbeeld API-sleutelverificatie wilt gebruiken, kunt u het verificatietype 'Anoniem' selecteren en de API-sleutel in de header opgeven.		 Nee
connectVia De Integration Runtime die moet worden gebruikt om verbinding te maken met het gegevensarchief. Meer informatie vindt u in de sectie Vereisten . Als deze eigenschap niet is opgegeven, wordt de standaard Azure Integration Runtime gebruikt. Nee

Zie de bijbehorende secties voor meer informatie voor verschillende verificatietypen.

Basisverificatie gebruiken

Stel de eigenschap authenticationType in op Basic. Geef naast de algemene eigenschappen die in de vorige sectie worden beschreven, de volgende eigenschappen op:

Eigenschappen Beschrijving Vereist
gebruikersnaam De gebruikersnaam die moet worden gebruikt voor toegang tot het REST-eindpunt. Ja
password Het wachtwoord voor de gebruiker (de waarde userName ). Markeer dit veld als een SecureString-type om het veilig op te slaan in Data Factory. U kunt ook verwijzen naar een geheim dat is opgeslagen in Azure Key Vault. Ja

Voorbeeld

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

Verificatie van service-principal gebruiken

Stel de eigenschap authenticationType in op AadServicePrincipal. Geef naast de algemene eigenschappen die in de vorige sectie worden beschreven, de volgende eigenschappen op:

Eigenschappen Beschrijving Vereist
servicePrincipalId Geef de client-id van de Microsoft Entra-toepassing op. Ja
servicePrincipalKey Geef de sleutel van de Microsoft Entra-toepassing op. Markeer dit veld als SecureString om het veilig op te slaan in Data Factory of verwijs naar een geheim dat is opgeslagen in Azure Key Vault. Ja
AD-tenant Geef de tenantgegevens (domeinnaam of tenant-id) op waaronder uw toepassing zich bevindt. Haal deze op door de muisaanwijzer in de rechterbovenhoek van Azure Portal te plaatsen. Ja
aadResourceId Geef de Microsoft Entra-resource op die u aanvraagt voor autorisatie, https://management.core.windows.netbijvoorbeeld. Ja
azureCloudType Geef voor service-principalverificatie het type Azure-cloudomgeving op waarnaar uw Microsoft Entra-toepassing is geregistreerd.
Toegestane waarden zijn AzurePublic, AzureChina, AzureUsGovernment en AzureGermany. Standaard wordt de cloudomgeving van de data factory gebruikt.		 Nee

Voorbeeld

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

Verificatie van OAuth2-clientreferenties gebruiken

Stel de eigenschap authenticationType in op OAuth2ClientCredential. Geef naast de algemene eigenschappen die in de vorige sectie worden beschreven, de volgende eigenschappen op:

Eigenschappen Beschrijving Vereist
tokenEndpoint Het tokeneindpunt van de autorisatieserver om het toegangstoken te verkrijgen. Ja
clientId De client-id die is gekoppeld aan uw toepassing. Ja
clientSecret Het clientgeheim dat is gekoppeld aan uw toepassing. Markeer dit veld als een SecureString-type om het veilig op te slaan in Data Factory. U kunt ook verwijzen naar een geheim dat is opgeslagen in Azure Key Vault. Ja
bereik Het bereik van de vereiste toegang. Hierin wordt beschreven wat voor soort toegang wordt aangevraagd. Nee
resource De doelservice of resource waarvoor de toegang wordt aangevraagd. Nee

Voorbeeld

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

Door het systeem toegewezen beheerde identiteitverificatie gebruiken

Stel de eigenschap authenticationType in op ManagedServiceIdentity. Geef naast de algemene eigenschappen die in de vorige sectie worden beschreven, de volgende eigenschappen op:

Eigenschappen Beschrijving Vereist
aadResourceId Geef de Microsoft Entra-resource op die u aanvraagt voor autorisatie, https://management.core.windows.netbijvoorbeeld. Ja

Voorbeeld

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

Door de gebruiker toegewezen beheerde identiteitverificatie gebruiken

Stel de eigenschap authenticationType in op ManagedServiceIdentity. Geef naast de algemene eigenschappen die in de vorige sectie worden beschreven, de volgende eigenschappen op:

Eigenschappen Beschrijving Vereist
aadResourceId Geef de Microsoft Entra-resource op die u aanvraagt voor autorisatie, https://management.core.windows.netbijvoorbeeld. Ja
aanmeldingsgegevens Geef de door de gebruiker toegewezen beheerde identiteit op als referentieobject. Ja

Voorbeeld

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

Verificatieheaders gebruiken

Daarnaast kunt u aanvraagheaders configureren voor verificatie, samen met de ingebouwde verificatietypen.

Voorbeeld: Api-sleutelverificatie gebruiken

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

Eigenschappen van gegevensset

Deze sectie bevat een lijst met eigenschappen die door de REST-gegevensset worden ondersteund.

Zie Gegevenssets en gekoppelde services voor een volledige lijst met secties en eigenschappen die beschikbaar zijn voor het definiëren van gegevenssets.

Als u gegevens uit REST wilt kopiëren, worden de volgende eigenschappen ondersteund:

Eigenschappen Beschrijving Vereist
type De typeeigenschap van de gegevensset moet worden ingesteld op RestResource. Ja
relativeUrl Een relatieve URL naar de resource die de gegevens bevat. Wanneer deze eigenschap niet is opgegeven, wordt alleen de URL gebruikt die is opgegeven in de definitie van de gekoppelde service. De HTTP-connector kopieert gegevens van de gecombineerde URL: [URL specified in linked service]/[relative URL specified in dataset]. Nee

Als u in additionalHeadersrequestBodypaginationRules de gegevensset en in de gegevensset bent ingesteldrequestMethod, wordt deze nog steeds ondersteund, terwijl u wordt aangeraden het nieuwe model in de toekomst te gebruiken.

Voorbeeld:

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

Eigenschappen van kopieeractiviteit

Deze sectie bevat een lijst met eigenschappen die worden ondersteund door de REST-bron en -sink.

Zie Pijplijnen voor een volledige lijst met secties en eigenschappen die beschikbaar zijn voor het definiëren van activiteiten.

REST als bron

De volgende eigenschappen worden ondersteund in de sectie bron van kopieeractiviteit:

Eigenschappen Beschrijving Vereist
type De typeeigenschap van de bron van de kopieeractiviteit moet worden ingesteld op RestSource. Ja
requestMethod De HTTP-methode. Toegestane waarden zijn GET (standaard) en POST. Nee
additionalHeaders Aanvullende HTTP-aanvraagheaders. Nee
requestBody De hoofdtekst voor de HTTP-aanvraag. Nee
pagineringRules De pagineringsregels voor het opstellen van aanvragen van de volgende pagina. Raadpleeg de ondersteuningssectie voor paginering over details. Nee
httpRequestTimeout De time-out (de timespanwaarde ) voor de HTTP-aanvraag om een antwoord te krijgen. Deze waarde is de time-out voor het ophalen van een antwoord, niet de time-out voor het lezen van antwoordgegevens. De standaardwaarde is 00:01:40. Nee
requestInterval De tijd die moet worden gewacht voordat de aanvraag voor de volgende pagina wordt verzonden. De standaardwaarde is 00:00:01 Nr.

Notitie

REST-connector negeert alle header 'Accepteren' die is opgegeven in additionalHeaders. Omdat REST-connector alleen antwoord in JSON ondersteunt, wordt er automatisch een header van Accept: application/jsongegenereerd.
De matrix van het object als de hoofdtekst van het antwoord wordt niet ondersteund in paginering.

Voorbeeld 1: De Get-methode gebruiken met paginering

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

Voorbeeld 2: De Post-methode gebruiken

"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 als sink

De volgende eigenschappen worden ondersteund in de sectie sink voor kopieeractiviteit:

Eigenschappen Beschrijving Vereist
type De typeeigenschap van de sink van de kopieeractiviteit moet worden ingesteld op RestSink. Ja
requestMethod De HTTP-methode. Toegestane waarden zijn POST (standaard), PUT en PATCH. Nee
additionalHeaders Aanvullende HTTP-aanvraagheaders. Nee
httpRequestTimeout De time-out (de timespanwaarde ) voor de HTTP-aanvraag om een antwoord te krijgen. Deze waarde is de time-out voor het ophalen van een antwoord, niet de time-out voor het schrijven van de gegevens. De standaardwaarde is 00:01:40. Nee
requestInterval De intervaltijd tussen verschillende aanvragen in milliseconden. De waarde van het aanvraaginterval moet een getal zijn tussen [10, 60000]. Nee
httpCompressionType Http-compressietype dat moet worden gebruikt tijdens het verzenden van gegevens met optimaal compressieniveau. Toegestane waarden zijn geen en gzip. Nee
writeBatchSize Aantal records dat moet worden geschreven naar de REST-sink per batch. De standaardwaarde is 10000. Nee

REST-connector als sink werkt met de REST API's die JSON accepteren. De gegevens worden verzonden in JSON met het volgende patroon. Indien nodig kunt u de toewijzing van het kopieeractiviteitsschema gebruiken om de brongegevens opnieuw vorm te geven om te voldoen aan de verwachte nettolading door de REST API.

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

Voorbeeld:

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

Eigenschappen van toewijzingsgegevensstroom

REST wordt ondersteund in gegevensstromen voor zowel integratiegegevenssets als inlinegegevenssets.

Brontransformatie

Eigenschappen Beschrijving Vereist
requestMethod De HTTP-methode. Toegestane waarden zijn GET en POST. Ja
relativeUrl Een relatieve URL naar de resource die de gegevens bevat. Wanneer deze eigenschap niet is opgegeven, wordt alleen de URL gebruikt die is opgegeven in de definitie van de gekoppelde service. De HTTP-connector kopieert gegevens van de gecombineerde URL: [URL specified in linked service]/[relative URL specified in dataset]. Nee
additionalHeaders Aanvullende HTTP-aanvraagheaders. Nee
httpRequestTimeout De time-out (de timespanwaarde ) voor de HTTP-aanvraag om een antwoord te krijgen. Deze waarde is de time-out voor het ophalen van een antwoord, niet de time-out voor het schrijven van de gegevens. De standaardwaarde is 00:01:40. Nee
requestInterval De intervaltijd tussen verschillende aanvragen in milliseconden. De waarde van het aanvraaginterval moet een getal zijn tussen [10, 60000]. Nee
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter'] 'request_query_parameter' is door de gebruiker gedefinieerd, die verwijst naar de naam van de ene queryparameter in de volgende HTTP-aanvraag-URL. Nee

Sinktransformatie

Eigenschappen Beschrijving Vereist
additionalHeaders Aanvullende HTTP-aanvraagheaders. Nee
httpRequestTimeout De time-out (de timespanwaarde ) voor de HTTP-aanvraag om een antwoord te krijgen. Deze waarde is de time-out voor het ophalen van een antwoord, niet de time-out voor het schrijven van de gegevens. De standaardwaarde is 00:01:40. Nee
requestInterval De intervaltijd tussen verschillende aanvragen in milliseconden. De waarde van het aanvraaginterval moet een getal zijn tussen [10, 60000]. Nee
httpCompressionType Http-compressietype dat moet worden gebruikt tijdens het verzenden van gegevens met optimaal compressieniveau. Toegestane waarden zijn geen en gzip. Nee
writeBatchSize Aantal records dat moet worden geschreven naar de REST-sink per batch. De standaardwaarde is 10000. Nee

U kunt de methoden verwijderen, invoegen, bijwerken en upsert instellen, evenals de relatieve rijgegevens die moeten worden verzonden naar de REST-sink voor CRUD-bewerkingen.

Data flow REST sink

Voorbeeld van een gegevensstroomscript

Let op het gebruik van een wijzigingsrijtransformatie vóór de sink om ADF te instrueren welk type actie moet worden ondernomen met uw REST-sink. Bijvoorbeeld invoegen, bijwerken, upsert, verwijderen.

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

Ondersteuning voor paginering

Wanneer u gegevens kopieert uit REST API's, beperkt de REST API normaal gesproken de nettoladinggrootte van de reactie van één aanvraag onder een redelijk aantal; terwijl u grote hoeveelheden gegevens wilt retourneren, wordt het resultaat gesplitst in meerdere pagina's en moeten bellers opeenvolgende aanvragen verzenden om de volgende pagina van het resultaat op te halen. Meestal is de aanvraag voor één pagina dynamisch en samengesteld door de informatie die wordt geretourneerd uit het antwoord van de vorige pagina.

Deze algemene REST-connector ondersteunt de volgende pagineringspatronen:

  • De absolute of relatieve URL van de volgende aanvraag = eigenschapswaarde in de huidige antwoordtekst
  • De absolute of relatieve URL van de volgende aanvraag = headerwaarde in huidige antwoordheaders
  • De queryparameter van de volgende aanvraag = eigenschapswaarde in de huidige antwoordtekst
  • De queryparameter van de volgende aanvraag = headerwaarde in huidige antwoordheaders
  • De header van de volgende aanvraag = eigenschapswaarde in de hoofdtekst van het huidige antwoord
  • Koptekst van volgende aanvraag = headerwaarde in huidige antwoordheaders

Pagineringsregels worden gedefinieerd als een woordenlijst in de gegevensset, die een of meer hoofdlettergevoelige sleutel-waardeparen bevat. De configuratie wordt gebruikt om de aanvraag te genereren vanaf de tweede pagina. De connector stopt met herhalen wanneer http-statuscode 204 (geen inhoud) wordt opgehaald of een van de JSONPath-expressies in 'pagineringRules' retourneert null.

Ondersteunde sleutels in pagineringsregels:

Toets Beschrijving
AbsoluteUrl Geeft de URL aan om de volgende aanvraag uit te voeren. Dit kan een absolute URL of een relatieve URL zijn.
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter'] 'request_query_parameter' is door de gebruiker gedefinieerd, die verwijst naar de naam van de ene queryparameter in de volgende HTTP-aanvraag-URL.
Headers. request_header OR-headers['request_header'] 'request_header' is door de gebruiker gedefinieerd, die verwijst naar de ene headernaam in de volgende HTTP-aanvraag.
EndCondition:end_condition 'end_condition' is door de gebruiker gedefinieerd, wat aangeeft welke voorwaarde de pagineringslus in de volgende HTTP-aanvraag beëindigt.
MaxRequestNumber Geeft het maximumaantal pagineringsaanvragen aan. Laat het leeg, betekent geen limiet.
SupportRFC5988 Dit is standaard ingesteld op waar als er geen pagineringsregel is gedefinieerd. U kunt deze regel uitschakelen door deze instelling in te stellen supportRFC5988 op false of deze eigenschap uit het script te verwijderen.

Ondersteunde waarden in pagineringsregels:

Weergegeven als Beschrijving
Headers. response_header OR-headers['response_header'] 'response_header' is door de gebruiker gedefinieerd, die verwijst naar één headernaam in het huidige HTTP-antwoord, waarvan de waarde wordt gebruikt om de volgende aanvraag uit te geven.
Een JSONPath-expressie die begint met $(die de hoofdmap van de hoofdtekst van het antwoord vertegenwoordigt) De hoofdtekst van het antwoord mag slechts één JSON-object en de matrix van het object bevatten, omdat de hoofdtekst van het antwoord niet wordt ondersteund. De JSONPath-expressie moet één primitieve waarde retourneren, die wordt gebruikt voor het uitgeven van de volgende aanvraag.

Notitie

De pagineringsregels in toewijzingsgegevensstromen verschillen van die in de kopieeractiviteit in de volgende aspecten:

  1. Bereik wordt niet ondersteund in toewijzingsgegevensstromen.
  2. [''] wordt niet ondersteund in toewijzingsgegevensstromen. Gebruik in plaats daarvan {} om een speciaal teken te ontsnappen. Bijvoorbeeld, body.{@odata.nextLink}waarvan het JSON-knooppunt @odata.nextLink een speciaal teken . bevat.
  3. De eindvoorwaarde wordt ondersteund in toewijzingsgegevensstromen, maar de syntaxis van de voorwaarde verschilt van die in de kopieeractiviteit. body wordt gebruikt om de hoofdtekst van het antwoord aan te geven in plaats van $. header wordt gebruikt om de antwoordheader aan te geven in plaats van headers. Hier volgen twee voorbeelden die dit verschil laten zien:
    • Voorbeeld 1:
      Copy-activiteit: "EndCondition:$.data": "Leeg"
      Toewijzingsgegevensstromen: "EndCondition:body.data": "Leeg"
    • Voorbeeld 2:
      Copy-activiteit: "EndCondition:headers.complete": "Exist"
      Toewijzingsgegevensstromen: "EndCondition:header.complete": "Exist"

Voorbeelden van pagineringsregels

Deze sectie bevat een lijst met voorbeelden voor instellingen voor pagineringsregels.

Voorbeeld 1: Variabelen in QueryParameters

Dit voorbeeld bevat de configuratiestappen voor het verzenden van meerdere aanvragen waarvan de variabelen zich in QueryParameters bevinden.

Meerdere aanvragen:

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

Stap 1: Invoer sysparm_offset={offset} in basis-URL of relatieve URL , zoals wordt weergegeven in de volgende schermopnamen:

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

or

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

Stap 2: Stel pagineringsregels in als optie 1 of optie 2:

  • Optie1: "QueryParameters.{ offset}" : "BEREIK:0:10000:1000"

  • Optie2: "AbsoluteUrl.{ offset}" : "BEREIK:0:10000:1000"

Voorbeeld 2:Variabelen in AbsoluteUrl

In dit voorbeeld vindt u de configuratiestappen voor het verzenden van meerdere aanvragen waarvan de variabelen zich in AbsoluteUrl bevinden.

Meerdere aanvragen:

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

Stap 1: Voer {id} in de basis-URL in de configuratiepagina van de gekoppelde service of relatieve URL in het deelvenster gegevenssetverbinding in.

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

or

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

Stap 2: Pagineringsregels instellen als 'AbsoluteUrl.{ id}" :"BEREIK:1:100:1".

Voorbeeld 3:Variabelen in kopteksten

Dit voorbeeld bevat de configuratiestappen voor het verzenden van meerdere aanvragen waarvan de variabelen zich in headers bevinden.

Meerdere aanvragen:
RequestUrl: https://example/table
Aanvraag 1: Header(id->0)
Aanvraag 2: Header(id->10)
......
Aanvraag 100: Header(id->100)

Stap 1: Invoer {id} in extra headers.

Stap 2: Pagineringsregels instellen als "Headers.{ id}" : "RARNGE:0:100:10".

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

Voorbeeld 4:Variabelen bevinden zich in AbsoluteUrl/QueryParameters/Headers, de eindvariabele is niet vooraf gedefinieerd en de eindvoorwaarde is gebaseerd op het antwoord

In dit voorbeeld vindt u configuratiestappen voor het verzenden van meerdere aanvragen waarvan de variabelen zich in AbsoluteUrl/QueryParameters/Headers bevinden, maar de eindvariabele niet is gedefinieerd. Voor verschillende antwoorden worden verschillende instellingen voor de eindvoorwaarderegel weergegeven in voorbeeld 4.1-4.6.

Meerdere aanvragen:

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

In dit voorbeeld zijn twee antwoorden opgetreden:

Antwoord 1:

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

Antwoord 2:

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

Stap 1: Stel het bereik van pagineringsregels in als voorbeeld 1 en laat het einde van het bereik leeg als 'AbsoluteUrl.{ offset}": "RANGE:0::1000".

Stap 2: Stel verschillende regels voor eindvoorwaarde in op basis van verschillende laatste antwoorden. Zie de onderstaande voorbeelden:

  • Voorbeeld 4.1: De paginering eindigt wanneer de waarde van het specifieke knooppunt in antwoord leeg is

    De REST API retourneert het laatste antwoord in de volgende structuur:

    {
    Data: []
}

    Stel de regel voor de eindvoorwaarde in als 'EndCondition:$.data': 'Leeg' om de paginering te beëindigen wanneer de waarde van het specifieke knooppunt in het antwoord leeg is.

    Screenshot showing the End Condition setting for Example 4.1.

  • Voorbeeld 4.2: De paginering eindigt wanneer de waarde van het specifieke knooppunt in antwoord niet bestaat

    De REST API retourneert het laatste antwoord in de volgende structuur:

    {}

    Stel de regel voor de eindvoorwaarde in als 'EndCondition:$.data': 'NonExist' om de paginering te beëindigen wanneer de waarde van het specifieke knooppunt in antwoord niet bestaat.

    Screenshot showing the End Condition setting for Example 4.2.

  • Voorbeeld 4.3: De paginering eindigt wanneer de waarde van het specifieke knooppunt in antwoord bestaat

    De REST API retourneert het laatste antwoord in de volgende structuur:

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

    Stel de regel voor de eindvoorwaarde in als 'EndCondition:$. Voltooid": 'Bestaan' om de paginering te beëindigen wanneer de waarde van het specifieke knooppunt in antwoord bestaat.

    Screenshot showing the End Condition setting for Example 4.3.

  • Voorbeeld 4.4: De paginering eindigt wanneer de waarde van het specifieke knooppunt in antwoord een door de gebruiker gedefinieerde const-waarde is

    De REST API retourneert het antwoord in de volgende structuur:

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

    ......

    En het laatste antwoord bevindt zich in de volgende structuur:

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

    Stel de regel voor de eindvoorwaarde in als 'EndCondition:$. Voltooid": "Const:true" om de paginering te beëindigen wanneer de waarde van het specifieke knooppunt in antwoord een door de gebruiker gedefinieerde const-waarde is.

    Screenshot showing the End Condition setting for Example 4.4.

  • Voorbeeld 4.5: De paginering eindigt wanneer de waarde van de headersleutel in reactie gelijk is aan door de gebruiker gedefinieerde const-waarde

    De headersleutels in REST API-antwoorden worden weergegeven in de onderstaande structuur:

    Antwoordheader 1: header(Complete->0)
    ......
    Laatste antwoordheader: header(Complete->1)

    Stel de regel voor de eindvoorwaarde in op EndCondition:headers. Voltooid": "Const:1" om de paginering te beëindigen wanneer de waarde van de headersleutel in antwoord gelijk is aan door de gebruiker gedefinieerde const-waarde.

    Screenshot showing the End Condition setting for Example 4.5.

  • Voorbeeld 4.6: De paginering eindigt wanneer de sleutel bestaat in de antwoordheader

    De headersleutels in REST API-antwoorden worden weergegeven in de onderstaande structuur:

    Antwoordheader 1: header()
    ......
    Laatste antwoordheader: header(CompleteTime->20220920)

    Stel de regel voor de eindvoorwaarde in op EndCondition:headers. CompleteTime: 'Exist' om de paginering te beëindigen wanneer de sleutel bestaat in de antwoordheader.

    Screenshot showing the End Condition setting for Example 4.6.

Voorbeeld 5: Eindvoorwaarde instellen om eindeloze aanvragen te voorkomen wanneer bereikregel niet is gedefinieerd

Dit voorbeeld bevat de configuratiestappen voor het verzenden van meerdere aanvragen wanneer de bereikregel niet wordt gebruikt. De eindvoorwaarde kan worden ingesteld op voorbeeld 4.1-4.6 om eindeloze aanvragen te voorkomen. De REST API retourneert een antwoord in de volgende structuur. In dat geval wordt de URL van de volgende pagina weergegeven in paging.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="
    }
}
...

Het laatste antwoord is:

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

Stap 1: Stel pagineringsregels in als 'AbsoluteUrl': '$.paging.next'.

Stap 2: Als next in het laatste antwoord altijd hetzelfde is met de laatste aanvraag-URL en niet leeg, worden eindeloze aanvragen verzonden. De eindvoorwaarde kan worden gebruikt om eindeloze aanvragen te voorkomen. Stel daarom de regel voor de eindvoorwaarde in op voorbeeld 4.1-4.6.

Voorbeeld 6:Stel het maximale aanvraagnummer in om eindeloze aanvragen te voorkomen

Stel MaxRequestNumber in om eindeloze aanvragen te voorkomen, zoals wordt weergegeven in de volgende schermopname:

Screenshot showing the Max Request Number setting for Example 6.

Voorbeeld 7:De RFC 5988-pagineringsregel wordt standaard ondersteund

De back-end haalt automatisch de volgende URL op op basis van de RFC 5988-stijlkoppelingen in de header.

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

Tip

Als u deze standaardpagineringsregel niet wilt inschakelen, kunt u deze instellen supportRFC5988false of verwijderen in het script.

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

Voorbeeld 8: De volgende aanvraag-URL is afkomstig uit de hoofdtekst van het antwoord wanneer paginering wordt gebruikt in toewijzingsgegevensstromen

In dit voorbeeld wordt aangegeven hoe u de pagineringsregel en de regel voor de eindvoorwaarde instelt in toewijzingsgegevensstromen wanneer de volgende aanvraag-URL afkomstig is uit de hoofdtekst van het antwoord.

Het antwoordschema wordt hieronder weergegeven:

Screenshot showing the response schema of Example 8.

De pagineringsregels moeten worden ingesteld als de volgende schermopname:

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

De paginering wordt standaard gestopt wanneer hoofdtekst wordt weergegeven. {@odata.nextLink}** is null of leeg.

Maar als de waarde van @odata.nextLink in de laatste antwoordtekst gelijk is aan de laatste aanvraag-URL, leidt dit tot de eindeloze lus. Als u deze voorwaarde wilt voorkomen, definieert u regels voor eindvoorwaarde.

  • Als de waarde in het laatste antwoord leeg is, kan de regel voor de eindvoorwaarde als volgt worden ingesteld:

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

  • Als de waarde van de volledige sleutel in de antwoordheader gelijk is aan waar, wordt het einde van de paginering aangegeven, kan de regel voor de eindvoorwaarde als volgt worden ingesteld:

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

Voorbeeld 9: De antwoordindeling is XML en de volgende aanvraag-URL komt uit de hoofdtekst van het antwoord wanneer paginering wordt gebruikt in toewijzingsgegevensstromen

In dit voorbeeld wordt aangegeven hoe u de pagineringsregel instelt in toewijzingsgegevensstromen wanneer de antwoordindeling XML is en de volgende aanvraag-URL afkomstig is uit de hoofdtekst van het antwoord. Zoals wordt weergegeven in de volgende schermopname, is de eerste URL https://< gebruiker.dfs.core.windows.NET/bugfix/test/movie_1.xml>

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

Het antwoordschema wordt hieronder weergegeven:

Screenshot showing the response schema of Example 9.

De syntaxis van de pagineringsregel is hetzelfde als in voorbeeld 8 en moet worden ingesteld zoals hieronder in dit voorbeeld:

Screenshot showing setting the pagination rule for Example 9.

JSON-antwoord exporteren zoals dit is

U kunt deze REST-connector gebruiken om het JSON-antwoord van de REST API te exporteren naar verschillende op bestanden gebaseerde winkels. Als u een dergelijke schemaagnostische kopie wilt bereiken, slaat u de sectie 'structuur' (ook wel schema genoemd) over in de gegevensset en schematoewijzing in de kopieeractiviteit.

Schematoewijzing

Als u gegevens wilt kopiëren van REST-eindpunt naar een tabellaire sink, raadpleegt u schematoewijzing.

Gerelateerde inhoud

Zie Ondersteunde gegevensarchieven en -indelingen voor een lijst met gegevensarchieven die door de kopieeractiviteit worden ondersteund als bronnen en sinks in Azure Data Factory.