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

Artikel
10/16/2024

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 Visual Studio, Invoke-RestMethod van PowerShell 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.

Blader naar het tabblad Beheren in uw Azure Data Factory- of Synapse-werkruimte en selecteer Gekoppelde services en selecteer vervolgens Nieuw:
- Azure Data Factory
- Azure Synapse
Zoek naar REST en selecteer de REST-connector.
Configureer de servicedetails, test de verbinding en maak de nieuwe gekoppelde service.

Configuratiedetails van connector

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
Verificatie van service-principal
Verificatie van OAuth2-clientreferenties
Door het systeem toegewezen beheerde identiteitverificatie
Door de gebruiker toegewezen beheerde identiteitverificatie
Anonieme verificatie

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
servicePrincipalCredentialType	Geef het referentietype op dat moet worden gebruikt voor verificatie van de service-principal. Toegestane waarden zijn `ServicePrincipalKey` en `ServicePrincipalCert`.	Nee
Voor ServicePrincipalKey
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.	Nee
Voor ServicePrincipalCert
servicePrincipalEmbeddedCert	Geef het base64 gecodeerde certificaat op van uw toepassing die is geregistreerd in Microsoft Entra-id en zorg ervoor dat het certificaatinhoudstype PKCS #12 is. Markeer dit veld als SecureString om het veilig op te slaan of verwijs naar een geheim dat is opgeslagen in Azure Key Vault. Ga naar deze sectie voor meer informatie over het opslaan van het certificaat in Azure Key Vault.	Nee
servicePrincipalEmbeddedCertPassword	Geef het wachtwoord van uw certificaat op als uw certificaat is beveiligd met een wachtwoord. Markeer dit veld als SecureString om het veilig op te slaan of verwijs naar een geheim dat is opgeslagen in Azure Key Vault.	Nee

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.net`bijvoorbeeld.	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 1: Verificatie van de service-principalsleutel gebruiken

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

Voorbeeld 2: Verificatie van service-principalcertificaat gebruiken

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

Het certificaat van de service-principal opslaan in Azure Key Vault

U hebt twee opties om het service-principal-certificaat op te slaan in Azure Key Vault:

Optie 1
1. Converteer het service-principal-certificaat naar een base64-tekenreeks. Meer informatie vindt u in dit artikel.
2. Sla de base64-tekenreeks op als een geheim in Azure Key Vault.
Optie 2

Als u het certificaat niet kunt downloaden uit Azure Key Vault, kunt u deze sjabloon gebruiken om het geconverteerde service-principalcertificaat op te slaan als een geheim in Azure Key Vault.

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.net`bijvoorbeeld.	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.net`bijvoorbeeld.	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 additionalHeadersrequestBody paginationRules 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.

REST-sink voor gegevensstromen

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:

Bereik wordt niet ondersteund in toewijzingsgegevensstromen.
[''] 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.
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:

Schermopname van één configuratie voor het verzenden van meerdere aanvragen waarvan de variabelen zich in queryparameters bevinden.

Schermopname van een andere configuratie voor het verzenden van meerdere aanvragen waarvan de variabelen zich in Queryparameters bevinden.

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.

Schermopname van één configuratie voor het verzenden van meerdere aanvragen waarvan de variabelen zich in absolute URL bevinden.

Schermopname van een andere configuratie voor het verzenden van meerdere aanvragen waarvan de variabelen zich in absolute URL bevinden.

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}: "BEREIK:0:100:10".

Schermopname van de pagineringsregel voor het verzenden van meerdere aanvragen waarvan de variabelen zich in headers bevinden.

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

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:

Schermopname van de instelling Max Request Number voor Voorbeeld 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.

Schermopname van voorbeelden van de HTTP-header die voldoet aan R F C 5988.

Tip

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

Schermopname die laat zien hoe u de instelling R F C 5988 voor voorbeeld 7 uitschakelt.

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:

Schermopname van het antwoordschema van voorbeeld 8.

De pagineringsregels moeten worden ingesteld als de volgende schermopname:

Schermopname van het instellen van de pagineringsregel voor voorbeeld 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:
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:

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>

Schermopname van de antwoordindeling X M L en de volgende aanvraag-URL is afkomstig uit de hoofdtekst van het antwoord.

Het antwoordschema wordt hieronder weergegeven:

Schermopname van het antwoordschema van voorbeeld 9.

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

Schermopname van het instellen van de pagineringsregel voor voorbeeld 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.

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

Share via

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

Ondersteunde mogelijkheden

Vereisten

Aan de slag

Een gekoppelde REST-service maken met behulp van de gebruikersinterface

Configuratiedetails van connector

Eigenschappen van gekoppelde service

Basisverificatie gebruiken

Verificatie van service-principal gebruiken

Het certificaat van de service-principal opslaan in Azure Key Vault

Verificatie van OAuth2-clientreferenties gebruiken

Door het systeem toegewezen beheerde identiteitverificatie gebruiken

Door de gebruiker toegewezen beheerde identiteitverificatie gebruiken

Verificatieheaders gebruiken

Eigenschappen van gegevensset

Eigenschappen van kopieeractiviteit

REST als bron

REST als sink

Eigenschappen van toewijzingsgegevensstroom

Brontransformatie

Sinktransformatie

Voorbeeld van een gegevensstroomscript

Voorbeeld 1: Variabelen in QueryParameters

Voorbeeld 2:Variabelen in AbsoluteUrl

Voorbeeld 3:Variabelen in kopteksten

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

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

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

JSON-antwoord exporteren zoals dit is

Schematoewijzing

Feedback

Aanvullende resources

Share via

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

Ondersteunde mogelijkheden

Vereisten

Aan de slag

Een gekoppelde REST-service maken met behulp van de gebruikersinterface

Configuratiedetails van connector

Eigenschappen van gekoppelde service

Basisverificatie gebruiken

Verificatie van service-principal gebruiken

Het certificaat van de service-principal opslaan in Azure Key Vault

Verificatie van OAuth2-clientreferenties gebruiken

Door het systeem toegewezen beheerde identiteitverificatie gebruiken

Door de gebruiker toegewezen beheerde identiteitverificatie gebruiken

Verificatieheaders gebruiken

Eigenschappen van gegevensset

Eigenschappen van kopieeractiviteit

REST als bron

REST als sink

Eigenschappen van toewijzingsgegevensstroom

Brontransformatie

Sinktransformatie

Voorbeeld van een gegevensstroomscript

Ondersteuning voor paginering

Voorbeelden van pagineringsregels

Voorbeeld 1: Variabelen in QueryParameters

Voorbeeld 2:Variabelen in AbsoluteUrl

Voorbeeld 3:Variabelen in kopteksten

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

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

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

Voorbeeld 7:De RFC 5988-pagineringsregel wordt standaard ondersteund

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

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

JSON-antwoord exporteren zoals dit is

Schematoewijzing

Gerelateerde inhoud

Feedback

Aanvullende resources