Megosztás a következőn keresztül:

Adatok másolása és átalakítása REST-végpontról és REST-végpontra az Azure Data Factory használatával

  • Cikk

A következőkre vonatkozik: Azure Data Factory Azure Synapse Analytics

Tipp.

Próbálja ki a Data Factoryt a Microsoft Fabricben, amely egy teljes körű elemzési megoldás a nagyvállalatok számára. A Microsoft Fabric az adattovábbítástól az adatelemzésig, a valós idejű elemzésig, az üzleti intelligenciáig és a jelentéskészítésig mindent lefed. Ismerje meg, hogyan indíthat új próbaverziót ingyenesen!

Ez a cikk azt ismerteti, hogyan használhatja az Azure Data Factoryban a másolási tevékenységet adatoknak a REST végpontba vagy onnan máshová történő másolásához. A cikk az Azure Data Factoryban történő másolási tevékenységre épül, amely általános áttekintést nyújt a másolási tevékenységről.

Az ezen REST-összekötő, HTTP-összekötő és a webtábla-összekötő közötti különbség a következő:

  • A REST-összekötő kifejezetten támogatja az adatok RESTful API-kból való másolását.
  • A HTTP-összekötő általánosan használható adatok lekérésére bármely HTTP-végpontról, például fájl letöltéséhez. Ezen REST-összekötő előtt előfordulhat, hogy Ön HTTP-összekötő használatával másol adatokat a RESTful API-kból, amely támogatott, de kevésbé célszerű a REST-összekötőhöz képest.
  • A webtábla-összekötő táblatartalmat nyer ki HTML-weblapról.

Támogatott képességek

Ez a REST-összekötő a következő képességekhez támogatott:

Támogatott képességek IR
Copy tevékenység (forrás/fogadó) (1) (2)
Adatfolyam leképezése (forrás/fogadó) (1)

(1) Azure-integrációs modul (2) Saját üzemeltetésű integrációs modul

A forrásként/fogadóként támogatott adattárak listáját a Támogatott adattárak című témakörben találja.

Ez az általános REST-összekötő a következőket támogatja:

  • Adatok másolása REST-végpontról a GET vagy POST metódusokkal, valamint adatok másolása REST-végpontra a POST, PUT vagy PATCH metódusok használatával.
  • Adatok másolása a következő hitelesítések egyikével: Névtelen, Alapszintű, Szolgáltatásnév, OAuth2 ügyfél-hitelesítő adatok, rendszer által hozzárendelt felügyelt identitás és felhasználó által hozzárendelt felügyelt identitás.
  • Lapozás a REST API-kban.
  • A REST mint forrás esetében másolja a REST JSON-választ, vagy elemezheti sémaleképezéssel. Csak a válasz hasznos adatai támogatottak a JSON-ban.

Tipp.

Ha a REST-összekötő Data Factoryben való konfigurálása előtt szeretné tesztelni az adatlekérési kérelmet, ismerje meg a fejléc- és törzskövetelmények API-specifikációját. Az ellenőrzéshez használhat olyan eszközöket, mint a Visual Studio, a PowerShell Invoke-RestMethod vagy egy webböngésző.

Előfeltételek

Ha az adattár helyszíni hálózaton, Azure-beli virtuális hálózaton vagy Amazon Virtual Private Cloudon belül található, konfigurálnia kell egy saját üzemeltetésű integrációs modult a csatlakozáshoz.

Ha az adattár felügyelt felhőalapú adatszolgáltatás, használhatja az Azure Integration Runtime-ot. Ha a hozzáférés a tűzfalszabályokban jóváhagyott IP-címekre korlátozódik, hozzáadhat azure integration runtime IP-eket az engedélyezési listához.

Az Azure Data Factory felügyelt virtuális hálózati integrációs moduljával is elérheti a helyszíni hálózatot anélkül, hogy saját üzemeltetésű integrációs modult telepítene és konfigurálna.

A Data Factory által támogatott hálózati biztonsági mechanizmusokkal és lehetőségekkel kapcsolatos további információkért lásd az adathozzáférési stratégiákat.

Első lépések

A Copy tevékenység folyamattal való végrehajtásához használja az alábbi eszközök vagy SDK-k egyikét:

REST társított szolgáltatás létrehozása felhasználói felületen

Az alábbi lépések végrehajtásával hozzon létre EGY REST társított szolgáltatást az Azure Portal felhasználói felületén.

  1. Keresse meg az Azure Data Factory vagy a Synapse-munkaterület Kezelés lapját, és válassza a Társított szolgáltatások lehetőséget, majd válassza az Új lehetőséget:

  2. Keresse meg a REST-et, és válassza ki a REST-összekötőt.

    Válassza a REST-összekötőt.

  3. Konfigurálja a szolgáltatás részleteit, tesztelje a kapcsolatot, és hozza létre az új társított szolgáltatást.

    A REST társított szolgáltatás konfigurálása.

Az összekötő konfigurációjának részletei

Az alábbi szakaszok a REST-összekötőre jellemző Data Factory-entitások meghatározásához használható tulajdonságok részleteit ismertetik.

Társított szolgáltatás tulajdonságai

A REST társított szolgáltatás esetében a következő tulajdonságok támogatottak:

Tulajdonság Leírás Kötelező
típus A típustulajdonságot RestService értékre kell állítani. Igen
url A REST szolgáltatás alap URL-címe. Igen
enableServerCertificateValidation A kiszolgálóoldali TLS/SSL-tanúsítvány érvényesítése a végponthoz való csatlakozáskor. Nem
(az alapértelmezett érték igaz)
authenticationType A REST szolgáltatáshoz való csatlakozáshoz használt hitelesítés típusa. Az engedélyezett értékek a Névtelen, az Alapszintű, az AadServicePrincipal, az OAuth2ClientCredential és a ManagedServiceIdentity. A hitelesítési fejléceket a tulajdonságban authHeaders is konfigurálhatja. További tulajdonságokat és példákat az alábbi szakaszokban talál. Igen
authHeaders További HTTP-kérelemfejlécek a hitelesítéshez.
Az API-kulcsos hitelesítés használatához például kiválaszthatja a hitelesítési típust "Névtelen" néven, és megadhatja az API-kulcsot a fejlécben.		 Nem
connectVia Az adattárhoz való csatlakozáshoz használható integrációs modul . További információ az Előfeltételek szakaszból. Ha nincs megadva, ez a tulajdonság az alapértelmezett Azure Integration Runtime-t használja. Nem

A különböző hitelesítési típusok részletes leírását a megfelelő szakaszokban találja.

Alapszintű hitelesítés használata

Állítsa az authenticationType tulajdonságot Alapszintű értékre. Az előző szakaszban ismertetett általános tulajdonságok mellett adja meg a következő tulajdonságokat:

Tulajdonság Leírás Kötelező
Felhasználónév A REST-végpont eléréséhez használandó felhasználónév. Igen
jelszó A felhasználó jelszava (a userName érték). Jelölje meg ezt a mezőt SecureString-típusként, hogy biztonságosan tárolja a Data Factoryben. Hivatkozhat az Azure Key Vaultban tárolt titkos kódokra is. Igen

Példa

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

Egyszerű szolgáltatáshitelesítés használata

Állítsa be az authenticationType tulajdonságot AadServicePrincipal értékre. Az előző szakaszban ismertetett általános tulajdonságok mellett adja meg a következő tulajdonságokat:

Tulajdonság Leírás Kötelező
servicePrincipalId Adja meg a Microsoft Entra-alkalmazás ügyfél-azonosítóját. Igen
servicePrincipalKey Adja meg a Microsoft Entra alkalmazás kulcsát. Jelölje meg ezt a mezőt SecureStringként, hogy biztonságosan tárolja a Data Factoryben, vagy hivatkozzon az Azure Key Vaultban tárolt titkos kódra. Igen
bérlő Adja meg azt a bérlői információt (tartománynevet vagy bérlőazonosítót), amely alatt az alkalmazás található. A lekéréshez vigye az egérmutatót az Azure Portal jobb felső sarkában. Igen
aadResourceId Adja meg például az engedélyezéshez kért Microsoft Entra-erőforrást https://management.core.windows.net. Igen
azureCloudType A Szolgáltatásnév hitelesítéséhez adja meg annak az Azure-felhőkörnyezetnek a típusát, amelyre a Microsoft Entra-alkalmazás regisztrálva van.
Az engedélyezett értékek az AzurePublic, az AzureChina, az AzureUsGovernment és az AzureGermany. Alapértelmezés szerint a data factory felhőkörnyezetét használja a rendszer.		 Nem

Példa

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

OAuth2-ügyfél hitelesítő adatainak hitelesítése

Állítsa az authenticationType tulajdonságot OAuth2ClientCredential értékre. Az előző szakaszban ismertetett általános tulajdonságok mellett adja meg a következő tulajdonságokat:

Tulajdonság Leírás Kötelező
tokenEndpoint Az engedélyezési kiszolgáló jogkivonatvégpontja a hozzáférési jogkivonat beszerzéséhez. Igen
clientId Az alkalmazáshoz társított ügyfélazonosító. Igen
clientSecret Az alkalmazáshoz társított ügyfélkód. Jelölje meg ezt a mezőt SecureString-típusként, hogy biztonságosan tárolja a Data Factoryben. Hivatkozhat az Azure Key Vaultban tárolt titkos kódokra is. Igen
hatálya A szükséges hozzáférés hatóköre. Leírja, hogy milyen típusú hozzáférésre lesz szükség. Nem
erőforrás A célszolgáltatás vagy erőforrás, amelyhez a hozzáférést kérni fogja. Nem

Példa

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

Rendszer által hozzárendelt felügyelt identitás hitelesítésének használata

Állítsa a authenticationType tulajdonságot ManagedServiceIdentity értékre. Az előző szakaszban ismertetett általános tulajdonságok mellett adja meg a következő tulajdonságokat:

Tulajdonság Leírás Kötelező
aadResourceId Adja meg például az engedélyezéshez kért Microsoft Entra-erőforrást https://management.core.windows.net. Igen

Példa

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

Felhasználó által hozzárendelt felügyelt identitás hitelesítésének használata

Állítsa a authenticationType tulajdonságot ManagedServiceIdentity értékre. Az előző szakaszban ismertetett általános tulajdonságok mellett adja meg a következő tulajdonságokat:

Tulajdonság Leírás Kötelező
aadResourceId Adja meg például az engedélyezéshez kért Microsoft Entra-erőforrást https://management.core.windows.net. Igen
hitelesítő adatok Adja meg a felhasználó által hozzárendelt felügyelt identitást hitelesítő objektumként. Igen

Példa

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

Hitelesítési fejlécek használata

Emellett konfigurálhatja a kérésfejléceket a hitelesítéshez a beépített hitelesítési típusokkal együtt.

Példa: API-kulcs hitelesítése

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

Adathalmaz tulajdonságai

Ez a szakasz a REST-adathalmaz által támogatott tulajdonságok listáját tartalmazza.

Az adathalmazok meghatározásához elérhető szakaszok és tulajdonságok teljes listáját az Adathalmazok és a csatolt szolgáltatások című témakörben találja.

Az adatok REST-ből való másolásához a következő tulajdonságok támogatottak:

Tulajdonság Leírás Kötelező
típus Az adathalmaz típustulajdonságának RestResource értékre kell állítania. Igen
relativeUrl Az adatokat tartalmazó erőforrás relatív URL-címe. Ha ez a tulajdonság nincs megadva, a rendszer csak a társított szolgáltatás definíciójában megadott URL-címet használja. A HTTP-összekötő adatokat másol a kombinált URL-címről: [URL specified in linked service]/[relative URL specified in dataset]. Nem

Ha a beállítást állította requestMethodbe, requestBody additionalHeadersés paginationRules az adathalmazban továbbra is támogatott, miközben a tevékenység továbbhaladásához javasolt az új modell használata.

Példa:

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

Másolási tevékenység tulajdonságai

Ez a szakasz a REST-forrás és a fogadó által támogatott tulajdonságok listáját tartalmazza.

A tevékenységek meghatározásához elérhető szakaszok és tulajdonságok teljes listáját a Folyamatok című témakörben találja.

REST mint forrás

A másolási tevékenység forrás szakaszában a következő tulajdonságok támogatottak:

Tulajdonság Leírás Kötelező
típus A másolási tevékenység forrásának típustulajdonságát RestSource-ra kell állítani. Igen
requestMethod A HTTP metódus. Az engedélyezett értékek a GET (alapértelmezett) és a POST. Nem
additionalHeaders További HTTP-kérelemfejlécek. Nem
requestBody A HTTP-kérés törzse. Nem
paginationRules A lapozási szabályok a következő oldalkérések írásához. Részletekért tekintse meg a lapszámozás támogatási szakaszát. Nem
httpRequestTimeout A HTTP-kérés időtúllépése (a TimeSpan értéke) a válasz lekéréséhez. Ez az érték a válasz lekéréséhez szükséges időtúllépés, nem pedig a válaszadatok olvasásának időtúllépése. Az alapértelmezett érték 00:01:40. Nem
requestInterval Várakozási idő a következő lapra vonatkozó kérés elküldése előtt. Az alapértelmezett érték 00:00:01 Nem

Feljegyzés

A REST-összekötő figyelmen kívül hagyja a megadott "Accept" fejlécet additionalHeaders. Mivel a REST-összekötő csak a JSON-ban támogatja a választ, automatikusan létrehoz egy fejlécet.Accept: application/json
A választörzsként megadott objektumtömb nem támogatott a lapozásban.

1. példa: A Get metódus használata lapszámozással

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

2. példa: A Post metódus használata

"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 fogadóként

A másolási tevékenység fogadó szakasza a következő tulajdonságokat támogatja:

Tulajdonság Leírás Kötelező
típus A másolási tevékenység fogadójának típustulajdonságát RestSink értékre kell állítani. Igen
requestMethod A HTTP metódus. Az engedélyezett értékek a POST (alapértelmezett), a PUT és a PATCH. Nem
additionalHeaders További HTTP-kérelemfejlécek. Nem
httpRequestTimeout A HTTP-kérés időtúllépése (a TimeSpan értéke) a válasz lekéréséhez. Ez az érték a válasz lekéréséhez szükséges időtúllépés, nem pedig az adatok írásához szükséges időtúllépés. Az alapértelmezett érték 00:01:40. Nem
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközi értékének [10, 600000] közötti számnak kell lennie. Nem
httpCompressionType AZ optimális tömörítési szinttel rendelkező adatok küldésekor használandó HTTP-tömörítési típus. Az engedélyezett értékek nem, és gzip. Nem
writeBatchSize A REST fogadóba kötegenként írandó rekordok száma. Az alapértelmezett érték 10000. Nem

A REST-összekötő fogadóként együttműködik a JSON-t elfogadó REST API-kkal. Az adatok JSON-ban lesznek elküldve az alábbi mintával. Szükség esetén a másolási tevékenység sémaleképezésével átformázhatja a forrásadatokat, hogy megfeleljenek a REST API által várt hasznos adatoknak.

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

Példa:

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

Adatfolyam-tulajdonságok leképezése

A REST az integrációs adathalmazok és a beágyazott adathalmazok adatfolyamaiban is támogatott.

Forrásátalakítás

Tulajdonság Leírás Kötelező
requestMethod A HTTP metódus. Az engedélyezett értékek a GET és a POST. Igen
relativeUrl Az adatokat tartalmazó erőforrás relatív URL-címe. Ha ez a tulajdonság nincs megadva, a rendszer csak a társított szolgáltatás definíciójában megadott URL-címet használja. A HTTP-összekötő adatokat másol a kombinált URL-címről: [URL specified in linked service]/[relative URL specified in dataset]. Nem
additionalHeaders További HTTP-kérelemfejlécek. Nem
httpRequestTimeout A HTTP-kérés időtúllépése (a TimeSpan értéke) a válasz lekéréséhez. Ez az érték a válasz lekéréséhez szükséges időtúllépés, nem pedig az adatok írásához szükséges időtúllépés. Az alapértelmezett érték 00:01:40. Nem
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközi értékének [10, 600000] közötti számnak kell lennie. Nem
QueryParameters. request_query_parameter VAGY QueryParameters[request_query_parameter] A "request_query_parameter" felhasználó által definiált, amely egy lekérdezési paraméter nevére hivatkozik a következő HTTP-kérelem URL-címében. Nem

Fogadó átalakítása

Tulajdonság Leírás Kötelező
additionalHeaders További HTTP-kérelemfejlécek. Nem
httpRequestTimeout A HTTP-kérés időtúllépése (a TimeSpan értéke) a válasz lekéréséhez. Ez az érték a válasz lekéréséhez szükséges időtúllépés, nem pedig az adatok írásához szükséges időtúllépés. Az alapértelmezett érték 00:01:40. Nem
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközi értékének [10, 600000] közötti számnak kell lennie. Nem
httpCompressionType AZ optimális tömörítési szinttel rendelkező adatok küldésekor használandó HTTP-tömörítési típus. Az engedélyezett értékek nem, és gzip. Nem
writeBatchSize A REST fogadóba kötegenként írandó rekordok száma. Az alapértelmezett érték 10000. Nem

Beállíthatja a törlési, beszúrási, frissítési és upsert metódusokat, valamint a relatív soradatokat a REST fogadóba a CRUD-műveletekhez.

Adatfolyam REST-fogadója

Adatfolyam-példaszkript

Figyelje meg, hogy a fogadó előtt egy módosítósor-átalakítással utasíthatja az ADF-et, hogy milyen típusú műveletet hajtson végre a REST-fogadóval. Például beszúrás, frissítés, upsert, delete.

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

Lapozás támogatása

Amikor adatokat másol a REST API-kból, a REST API általában ésszerű szám alatt korlátozza az egyetlen kérelem válasz hasznos adatmennyiségének méretét; nagy mennyiségű adat visszaadásához az eredményt több oldalra osztja, és megköveteli a hívóktól, hogy egymást követő kéréseket küldjenek az eredmény következő oldalának lekéréséhez. Az egyik oldal kérése általában dinamikus, és az előző oldal válaszából visszaadott információkból áll.

Ez az általános REST-összekötő a következő lapozási mintákat támogatja:

  • Következő kérés abszolút vagy relatív URL-címe = tulajdonságérték az aktuális válasz törzsében
  • Következő kérés abszolút vagy relatív URL-címe = fejlécérték az aktuális válaszfejlécekben
  • Következő kérés lekérdezési paramétere = tulajdonságérték az aktuális válasz törzsében
  • Következő kérés lekérdezési paramétere = fejlécérték az aktuális válaszfejlécekben
  • Következő kérés fejléce = tulajdonságérték az aktuális válasz törzsében
  • Következő kérés fejléce = élőfej értéke az aktuális válaszfejlécekben

A lapozási szabályok szótárként vannak definiálva az adathalmazban, amely egy vagy több kis- és nagybetűket megkülönböztető kulcs-érték párot tartalmaz. A konfigurációval a rendszer a második oldaltól kezdve hozza létre a kérést. Az összekötő leállítja az iterálást, ha a HTTP-állapotkód 204(Nincs tartalom) lesz, vagy a "paginationRules" JSONPath-kifejezéseinek bármelyike null értéket ad vissza.

Támogatott kulcsok a lapozási szabályokban:

Kulcs Leírás
AbsoluteUrl Azt az URL-címet jelzi, amely a következő kérést küldi ki. Ez lehet abszolút VAGY relatív URL-cím.
QueryParameters. request_query_parameter VAGY QueryParameters[request_query_parameter] A "request_query_parameter" felhasználó által definiált, amely egy lekérdezési paraméter nevére hivatkozik a következő HTTP-kérelem URL-címében.
Fejlécek. request_header VAGY fejlécek[request_header] A "request_header" felhasználó által definiált, amely a következő HTTP-kérelem egyik fejlécnevére hivatkozik.
EndCondition:end_condition A "end_condition" felhasználó által definiált, amely azt a feltételt jelzi, amely a következő HTTP-kérelemben lezárja a lapozási ciklust.
MaxRequestNumber A lapozási kérelem maximális számát jelzi. Hagyja üresként, azt jelenti, hogy nincs korlát.
SupportRFC5988 Alapértelmezés szerint ez igaz értékre van állítva, ha nincs megadva lapozási szabály. Ezt a szabályt letilthatja úgy, hogy hamis értéket állít be supportRFC5988 , vagy eltávolítja ezt a tulajdonságot a szkriptből.

Támogatott értékek a lapozási szabályokban:

Érték Leírás
Fejlécek. response_header VAGY fejlécek[response_header] A "response_header" felhasználó által definiált, amely az aktuális HTTP-válaszban egy fejlécnévre hivatkozik, amelynek értéke a következő kérés kiállításához lesz felhasználva.
Egy "$" kezdetű JSONPath-kifejezés (amely a válasz törzsének gyökerét jelöli) A válasz törzsének csak egy JSON-objektumot és objektumtömböt kell tartalmaznia, mivel a választörzs nem támogatott. A JSONPath-kifejezésnek egyetlen primitív értéket kell visszaadnia, amelyet a rendszer a következő kérés kiállításához használ.

Feljegyzés

A leképezési adatfolyamok lapozási szabályai eltérnek a másolási tevékenységben a következő szempontok szerint:

  1. A tartomány nem támogatott az adatfolyamok leképezésében.
  2. [''] az adatfolyamok leképezése nem támogatott. Ehelyett használja {} a speciális karaktert. Például, body.{@odata.nextLink}amelynek JSON-csomópontja @odata.nextLink speciális karaktert . tartalmaz.
  3. A záró feltétel támogatott az adatfolyamok leképezésében, de a feltétel szintaxisa eltér attól a másolási tevékenységnél. body a válasz törzsének jelzésére $szolgál ahelyett, hogy . header a válasz fejlécének jelzésére headersszolgál ahelyett, hogy . Az alábbi két példa mutatja be ezt a különbséget:
    • 1. példa:
      Copy tevékenység: "EndCondition:$.data": "Empty"
      Adatfolyamok leképezése: "EndCondition:body.data": "Empty"
    • 2. példa:
      Copy tevékenység: "EndCondition:headers.complete": "Exist"
      Adatfolyamok leképezése: "EndCondition:header.complete": "Exist"

Példák lapozási szabályokra

Ez a szakasz a lapozási szabályok beállításaira vonatkozó példák listáját tartalmazza.

1. példa: Változók a QueryParametersben

Ez a példa több olyan kérés küldésének konfigurációs lépéseit ismerteti, amelyek változói a QueryParametersben találhatók.

Több kérés:

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

1. lépés: Bemenet sysparm_offset={offset} vagy alap URL-címben vagy relatív URL-címben az alábbi képernyőképeken látható módon:

Képernyőkép egy konfigurációról, amely több kérést küld, amelyek változói a lekérdezési paraméterekben találhatók.

vagy

Képernyőkép egy másik konfigurációról, amely több kérést küld, amelyek változói a lekérdezési paraméterekben találhatók.

2. lépés: Lapozási szabályok beállítása az 1. vagy a 2. lehetőségként:

  • 1. lehetőség: "QueryParameters.{ offset}" : "RANGE:0:10000:1000"

  • 2. lehetőség: "AbsoluteUrl.{ offset}" : "RANGE:0:10000:1000"

2. példa: Változók az AbsoluteUrl-ben

Ez a példa bemutatja a konfigurációs lépéseket több olyan kérés küldéséhez, amelyek változói az AbsoluteUrl-ben találhatók.

Több kérés:

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

1. lépés: Bemenet {id} vagy az alap URL-címben a társított szolgáltatás konfigurációs lapján, vagy relatív URL-cím az adathalmaz kapcsolatpaneljén.

Képernyőkép egy konfigurációról, amely több kérést küld, amelyek változói abszolút URL-címben találhatók.

vagy

Képernyőkép egy másik konfigurációról, amely több kérést küld, amelyek változói abszolút URL-címben találhatók.

2. lépés: Lapozási szabályok beállítása "AbsoluteUrl.{ id}" :"RANGE:1:100:1".

3. példa: Változók a fejlécekben

Ez a példa a konfigurációs lépéseket mutatja be több olyan kérés elküldéséhez, amelyek változói fejlécekben találhatók.

Több kérés:
RequestUrl: https://example/table
1. kérelem: Header(id->0)
2. kérelem: Header(id->10)
......
100. kérelem: Header(id->100)

1. lépés: Bemenet {id} a további fejlécekben.

2. lépés: Lapozási szabályok beállítása "Fejlécek" értékre. { id}" : "RARNGE:0:100:10".

Képernyőkép a lapozási szabályról, amely több olyan kérést küld, amelynek változói fejlécekben találhatók.

4. példa: A változók az AbsoluteUrl/QueryParameters/Headers függvényben találhatók, a végváltozó nincs előre definiálva, a záró feltétel pedig a válaszon alapul

Ez a példa konfigurációs lépéseket tartalmaz több olyan kérés küldéséhez, amelyek változói Az AbsoluteUrl/QueryParameters/Headers elemben találhatók, de a záró változó nincs definiálva. Különböző válaszok esetén a 4.1–4.6. példában különböző feltételszabály-beállítások jelennek meg.

Több kérés:

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

Ebben a példában két válasz történt:

1. válasz:

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

2. válasz:

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

1. lépés: Állítsa be a lapozási szabályok tartományát 1. példaként, és hagyja üresen a tartomány végét "AbsoluteUrl.{ offset}": "RANGE:0::1000".

2. lépés: Állítsa be a különböző zárófeltétel-szabályokat a különböző utolsó válaszok szerint. Lásd az alábbi példákat:

  • 4.1. példa: A lapozás akkor fejeződik be, ha a válaszban szereplő adott csomópont értéke üres

    A REST API az alábbi struktúrában adja vissza az utolsó választ:

    {
    Data: []
}

    Állítsa a záró feltétel szabályát "EndCondition:$.data": "Empty" értékre a lapozás befejezéséhez, ha a válaszban szereplő adott csomópont értéke üres.

    Képernyőkép a 4.1- példához tartozó Feltétel végbeállításról.

  • 4.2. példa: A lapozás akkor ér véget, ha a válaszban szereplő adott csomópont értéke nem létezik

    A REST API az alábbi struktúrában adja vissza az utolsó választ:

    {}

    Állítsa a záró feltétel szabályát "EndCondition:$.data": "NonExist" értékre a lapozás befejezéséhez, ha a válaszban szereplő adott csomópont értéke nem létezik.

    Képernyőkép a 4.2. példához tartozó Feltétel végbeállításról.

  • 4.3. példa: A lapozás akkor fejeződik be, ha a válaszban szereplő adott csomópont értéke létezik

    A REST API az alábbi struktúrában adja vissza az utolsó választ:

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

    Állítsa be a zárófeltétel-szabályt "EndCondition:$" értékre . Kész: "Létező" a lapozás befejezéséhez, ha a válaszban szereplő adott csomópont értéke létezik.

    Képernyőkép a 4.3. példához tartozó Feltétel végbeállításról.

  • 4.4. példa: A lapozás akkor fejeződik be, ha a válaszban szereplő adott csomópont értéke felhasználó által megadott const érték

    A REST API a következő struktúrában adja vissza a választ:

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

    ......

    Az utolsó válasz pedig a következő struktúrában van:

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

    Állítsa be a zárófeltétel-szabályt "EndCondition:$" értékre . Kész: "Const:true" a lapozás befejezéséhez, ha a válaszban szereplő adott csomópont értéke felhasználó által megadott const érték.

    Képernyőkép a 4.4- példához tartozó Feltétel végbeállításról.

  • 4.5. példa: A lapozás akkor ér véget, ha a válaszban szereplő fejléckulcs értéke megegyezik a felhasználó által megadott const értékkel

    A REST API-válaszok fejléckulcsai az alábbi struktúrában jelennek meg:

    Válaszfejléc 1: header(Complete->0)
    ......
    Utolsó válasz fejléce: header(Complete->1)

    Állítsa be a zárófeltétel-szabályt "EndCondition:headers" értékre . Kész: "Const:1" a lapozás befejezéséhez, ha a válaszban szereplő fejléckulcs értéke megegyezik a felhasználó által megadott const értékkel.

    Képernyőkép a 4.5-ös példa zárófeltétel-beállításával.

  • 4.6. példa: A lapozás akkor fejeződik be, ha a kulcs megtalálható a válaszfejlécben

    A REST API-válaszok fejléckulcsai az alábbi struktúrában jelennek meg:

    Válaszfejléc 1: header()
    ......
    Utolsó válasz fejléce: header(CompleteTime->20220920)

    Állítsa be a zárófeltétel-szabályt "EndCondition:headers" értékre . CompleteTime: "Exist" (Létezik) a lapozás befejezéséhez, ha a kulcs megtalálható a válaszfejlécben.

    Képernyőkép a 4.6-os példa zárófeltétel-beállításával.

5. példa: A végfeltétel beállítása a végtelen kérések elkerülése érdekében, ha a tartományszabály nincs meghatározva

Ez a példa több kérés küldésének konfigurációs lépéseit ismerteti, ha a tartományszabályt nem használják. A végfeltétel a 4.1–4.6. példában állítható be a végtelen kérések elkerülése érdekében. A REST API a következő struktúrában ad vissza választ, ebben az esetben a következő oldal URL-címe a paging.next fájlban jelenik meg.

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

Az utolsó válasz a következő:

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

1. lépés: A lapozási szabályok beállítása "AbsoluteUrl": "$.paging.next".

2. lépés: Ha next az utolsó válasz mindig megegyezik az utolsó kérés URL-címével, és nem üres, a rendszer végtelen kéréseket küld. A végfeltétel a végtelen kérések elkerülésére használható. Ezért állítsa be a zárófeltétel-szabályt a 4.1-4.6. példára hivatkozva.

6. példa: A kérelem maximális számának beállítása a végtelen kérés elkerülése érdekében

Állítsa be a MaxRequestNumber függvényt, hogy elkerülje a végtelen kérést az alábbi képernyőképen látható módon:

Képernyőkép a 6. példához tartozó Maximális kérelemszám beállításról.

7. példa: Az RFC 5988 lapozási szabály alapértelmezés szerint támogatott

A háttérrendszer automatikusan megkapja a következő URL-címet a fejlécben található RFC 5988 stílusú hivatkozások alapján.

Képernyőkép az R F C 5988-nak megfelelő HTTP-fejléc mintáiról.

Tipp.

Ha nem szeretné engedélyezni ezt az alapértelmezett lapozási szabályt, beállíthatja supportRFC5988 false vagy egyszerűen törölheti azt a szkriptben.

Képernyőkép a 7. példa R F C 5988 beállításának letiltásáról.

8. példa: A következő kérés URL-címe a válasz törzséből származik, amikor lapozást használ az adatfolyamok leképezéséhez

Ez a példa bemutatja, hogyan állíthatja be a lapozási szabályt és a zárófeltétel-szabályt az adatfolyamok leképezésében, amikor a következő kérelem URL-címe a válasz törzséből származik.

A válaszséma az alábbiakban látható:

Képernyőkép a 8. példa válaszsémáról.

A lapozási szabályokat a következő képernyőképként kell beállítani:

Képernyőkép a 8. példa lapozási szabályának beállításáról.

Alapértelmezés szerint a lapozás leáll, amikor a törzs. A(z) {@odata.nextLink}** értéke null vagy üres.

Ha azonban az utolsó válasz törzsében lévő @odata.nextLink értéke megegyezik az utolsó kérés URL-címével, akkor az a végtelen ciklushoz vezet. A feltétel elkerülése érdekében definiáljon zárófeltétel-szabályokat.

  • Ha az utolsó válasz értéke Üres, akkor a záró feltétel szabálya az alábbi módon állítható be:

    Képernyőkép a zárófeltétel-szabály beállításról, amikor az utolsó válasz üres.

  • Ha a válaszfejléc teljes kulcsának értéke true (igaz) értékű, a lapozás végét jelzi, akkor a zárófeltétel-szabály az alábbi módon állítható be:

    Képernyőkép a végfeltétel-szabály beállításáról, ha a válaszfej teljes kulcsa igaz értékű, a lapozás végét jelzi.

9. példa: A válasz formátuma XML, a következő kérés URL-címe pedig a válasz törzséből származik, amikor lapozást használ az adatfolyamok leképezéséhez

Ez a példa bemutatja, hogyan állíthatja be a lapozási szabályt az adatfolyamok leképezésében, ha a válaszformátum XML, a következő kérelem URL-címe pedig a válasz törzséből származik. Ahogy az alábbi képernyőképen látható, az első URL-cím a https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

Képernyőkép a válaszformátumról: X M L, a következő kérelem U R L pedig a válasz törzséből származik.

A válaszséma az alábbiakban látható:

Képernyőkép a 9. példa válaszsémáról.

A lapozási szabály szintaxisa ugyanaz, mint a 8. példában, és az alábbi módon kell beállítani:

Képernyőkép a 9. példa lapozási szabályának beállításával.

JSON-válasz exportálása a következőképpen

Ezt a REST-összekötőt használhatja a REST API JSON-válaszának különböző fájlalapú tárolókba való exportálásához. Az ilyen séma-agnosztikus másolás eléréséhez hagyja ki a "struktúra" (más néven séma) szakaszt az adathalmazban és a sémaleképezést a másolási tevékenységben.

Séma-hozzárendelés

Ha a REST-végpontról táblázatos fogadóba szeretne adatokat másolni, tekintse meg a sémaleképezést.

Kapcsolódó tartalom

AzOknak az adattáraknak a listáját, amelyeket a Másolási tevékenység forrásként és fogadóként támogat az Azure Data Factoryben, tekintse meg a támogatott adattárakat és formátumokat.