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

    Select REST connector.

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

    Configure REST linked service.

Csatlakozás or 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, requestBodyadditionalHeadersé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.

Data flow REST sink

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:

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

vagy

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

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ímbena társított szolgáltatás konfigurációs lapján, vagy relatív URL-cím az adathalmaz kapcsolatpaneljén.

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

vagy

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

2. lépés: Lapozási szabályokbeá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".

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

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.

    Screenshot showing the End Condition setting for Example 4.1.

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

    Screenshot showing the End Condition setting for Example 4.2.

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

    Screenshot showing the End Condition setting for Example 4.3.

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

    Screenshot showing the End Condition setting for Example 4.4.

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

    Screenshot showing the End Condition setting for Example 4.5.

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

    Screenshot showing the End Condition setting for Example 4.6.

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ályokbeá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:

Screenshot showing the Max Request Number setting for Example 6.

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.

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

Tipp.

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

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

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ó:

Screenshot showing the response schema of Example 8.

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

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

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:

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

  • 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:

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

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>

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

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

Screenshot showing the response schema of Example 9.

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

Screenshot showing setting the pagination rule for Example 9.

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.