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

A KÖVETKEZŐKRE VONATKOZIK: Azure Data Factory Azure Synapse Analytics

Ez a cikk azt ismerteti, hogyan használhatja a másolási tevékenységet a Azure Data Factory az adatok REST-végpontról és végpontra történő másolásához. A cikk a Azure Data Factory másolási tevékenységére épül, amely általános áttekintést nyújt a másolási tevékenységről.

A REST-összekötő, a 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 történő 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. A REST-összekötő előtt előfordulhat, hogy HTTP-összekötő használatával másol adatokat a RESTful API-kból, ami támogatott, de kevésbé funkcionális a REST-összekötőhöz képest.
  • A webes tábla összekötője kinyeri a táblázat tartalmát egy HTML-weblapról.

Támogatott képességek

A REST-forrásból bármilyen támogatott fogadóadattárba másolhat adatokat. A támogatott forrásadattárak adatait rest-fogadóba is másolhatja. A másolási tevékenység által forrásként és fogadóként támogatott adattárak listáját a támogatott adattárak és formátumok 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ódusokkal.
  • Adatok másolása a következő hitelesítések egyikével: Névtelen, Alapszintű, AAD szolgáltatásnév é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 adott állapotában , vagy elemezheti sémaleképezés használatával. Csak a válasz hasznos adatai támogatottak JSON-ban .

Tipp

Ha tesztelni szeretné az adatlekérési kérelmet, mielőtt konfigurálja a REST-összekötőt a Data Factoryben, 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 egy helyszíni hálózaton, egy Azure-beli virtuális hálózaton vagy az Amazon Virtual Private Cloudban 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. Ha a hozzáférés a tűzfalszabályokban jóváhagyott IP-címekre korlátozódik, felveheti az Azure Integration Runtime IP-címeket az engedélyezési listára.

Az Azure Data Factory felügyelt virtuális hálózati integrációs modul funkciójával is hozzáférhet a helyszíni hálózathoz 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.

Bevezetés

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

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

Az alábbi lépésekkel hozzon létre egy REST társított szolgáltatást a Azure Portal felhasználói felületén.

  1. Tallózással lépjen a Azure Data Factory vagy Synapse-munkaterület Kezelés lapjára, válassza a Társított szolgáltatások lehetőséget, majd kattintson az Új gombra:

  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.

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

Az alábbi szakaszokban a REST-összekötőre jellemző Data Factory-entitások meghatározásához használható tulajdonságokat ismertetjük.

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

Fontos

Az Azure-szolgáltatás biztonsági és megfelelőségi kérése miatt a rendszer által hozzárendelt felügyelt identitás hitelesítése már nem érhető el a REST-összekötőben a másolási és leképezési adatfolyamhoz. Javasoljuk, hogy olyan meglévő társított szolgáltatásokat telepítsen át, amelyek rendszer által felügyelt identitáshitelesítést használnak a felhasználó által hozzárendelt felügyelt identitáshitelesítésre vagy más hitelesítési típusra. Győződjön meg arról, hogy a migrálás 2022. szeptember 15-ig megtörténik. A felhasználó által hozzárendelt felügyelt identitások létrehozásával és kezelésével kapcsolatos részletes lépésekért tekintse meg ezt a témakört.

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ágotRestService értékre kell állítani. Yes
url A REST szolgáltatás alap URL-címe. Yes
enableServerCertificateValidation A kiszolgálóoldali TLS-/SSL-tanúsítvány érvényesítése a végponthoz való csatlakozáskor. No
(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: Névtelen, Alapszintű, AadServicePrincipal és ManagedServiceIdentity. A felhasználóalapú OAuth nem támogatott. Emellett hitelesítési fejléceket is konfigurálhat a tulajdonságban authHeader . További tulajdonságokat és példákat az alábbi szakaszokban talál. Yes
authHeaders További HTTP-kérésfejlécek a hitelesítéshez.
Az API-kulcsos hitelesítés használatához például kiválaszthatja a "Névtelen" hitelesítési típust, és megadhatja az API-kulcsot a fejlécben.
No
connectVia Az adattárhoz való csatlakozáshoz használandó Integration Runtime. További információ az Előfeltételek szakaszból. Ha nincs megadva, ez a tulajdonság az alapértelmezett Azure-Integration Runtime használja. No

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ő
userName (Felhasználónév) A REST-végpont eléréséhez használandó felhasználónév. Yes
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 Factoryban. Hivatkozhat az Azure Key Vault tárolt titkos kódra is. Yes

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

AAD egyszerű szolgáltatáshitelesítés használata

Állítsa 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 Azure Active Directory alkalmazás ügyfél-azonosítóját. Yes
servicePrincipalKey Adja meg a Azure Active Directory alkalmazás kulcsát. Jelölje meg ezt a mezőt SecureString-ként, hogy biztonságosan tárolja a Data Factoryben, vagy hivatkozzon egy Azure-Key Vault tárolt titkos kódra. Yes
bérlő Adja meg a bérlői adatokat (tartománynevet vagy bérlőazonosítót), amelyek alatt az alkalmazás található. A lekéréshez vigye az egérmutatót a Azure Portal jobb felső sarkában. Yes
aadResourceId Adja meg például a AAD erőforrást, https://management.core.windows.netamely engedélyezését kéri. Yes
azureCloudType A szolgáltatásnév hitelesítéséhez adja meg, hogy milyen típusú Azure-felhőkörnyezetben regisztrálja az AAD-alkalmazást.
Az engedélyezett értékek: AzurePublic, AzureChina, AzureUsGovernment és AzureGermany. Alapértelmezés szerint az adat-előállító felhőkörnyezetét használja a rendszer.
No

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": "<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 az 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 a AAD erőforrást, https://management.core.windows.netamely engedélyezését kéri. Yes
hitelesítő adatok Adja meg a felhasználó által hozzárendelt felügyelt identitást hitelesítőadat-objektumként. Yes

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>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Hitelesítési fejlécek használata

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

Példa: API-kulcsos hitelesítés használata

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Adatkészlet 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 társított 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. Yes
relativeUrl Az adatokat tartalmazó erőforrás relatív URL-címe. Ha nincs megadva ez a tulajdonság, 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]. No

Ha a beállítást állította be requestMethod, requestBodyadditionalHeadersés paginationRules az adatkészletben is, akkor is támogatott, miközben a tevékenység továbbhaladása során az új modell használatát javasoljuk.

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 forrásként

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

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. Yes
requestMethod A HTTP-metódus. Az engedélyezett értékek a GET (alapértelmezett) és a POST. No
additionalHeaders További HTTP-kérésfejlécek. No
requestBody A HTTP-kérés törzse. No
paginationRules A lapozási szabályok a következő oldalkérések megírásához. Részletekért tekintse meg a lapozás támogatásáról szóló szakaszt. No
httpRequestTimeout A HTTP-kérés időtúllépése ( 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. No
requestInterval A következő lapra vonatkozó kérés elküldése előtt várandó idő. Az alapértelmezett érték 00:00:01 No

Megjegyzés

A REST-összekötő figyelmen kívül hagyja a megadott "Elfogadás" fejlécet.additionalHeaders Mivel a REST-összekötő csak a JSON-ban támogatja a választ, automatikusan létrehoz egy fejlécet a következőből Accept: application/json: .

1. példa: A Get metódus használata lapozá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. Yes
requestMethod A HTTP-metódus. Az engedélyezett értékek a POST (alapértelmezett), PUT és PATCH. No
additionalHeaders További HTTP-kérésfejlécek. No
httpRequestTimeout A HTTP-kérés időtúllépése ( 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. No
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközének [10, 60000] közötti számnak kell lennie. No
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 értékek. No
writeBatchSize Kötegenként a REST-fogadóba írandó rekordok száma. Az alapértelmezett érték 10000. No

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 átalakíthatja 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 é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. Yes
relativeUrl Az adatokat tartalmazó erőforrás relatív URL-címe. Ha nincs megadva ez a tulajdonság, 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]. No
additionalHeaders További HTTP-kérésfejlécek. No
httpRequestTimeout A HTTP-kérés időtúllépése ( 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. No
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközének [10, 60000] közötti számnak kell lennie. No
Lekérdezésparaméterek. request_query_parameter OR QueryParameters[request_query_parameter] A "request_query_parameter" felhasználó által definiált, amely a következő HTTP-kérelem URL-címében egy lekérdezési paraméter nevére hivatkozik. No

Fogadó transzformációja

Tulajdonság Leírás Kötelező
additionalHeaders További HTTP-kérésfejlécek. No
httpRequestTimeout A HTTP-kérés időtúllépése ( 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. No
requestInterval A különböző kérések közötti időköz ezredmásodpercben. A kérelem időközének [10, 60000] közötti számnak kell lennie. No
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 értékek. No
writeBatchSize Kötegenként a REST-fogadóba írandó rekordok száma. Az alapértelmezett érték 10000. No

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

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

A REST API-kból történő adatmásoláskor a REST API általában ésszerű számú kérelemre korlátozza a válasz hasznos adatmennyiségét; nagy mennyiségű adat visszaadásához az eredményt több oldalra osztja fel, és megköveteli, hogy a hívók 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érelem abszolút vagy relatív URL-címe = tulajdonságérték az aktuális válasz törzsében
  • A következő kérelem 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 = fejlécérték az aktuális válaszfejlécekben

A tördelés szabályai az adatkészlet szótáraként vannak definiálva, amely egy vagy több kis- és nagybetűket megkülönböztető kulcs-érték párt tartalmaz. A rendszer a konfigurációval hozza létre a kérést a második oldaltól kezdve. Az összekötő leállítja az iterációt, amikor a 204-as (nincs tartalom) HTTP-állapotkódot kapja, vagy a "paginationRules" bármely JSONPath-kifejezése null értéket ad vissza.

A lapozási szabályokban támogatott kulcsok:

Kulcs Leírás
AbsoluteUrl Azt az URL-címet jelzi, amely a következő kérést ki szeretné küldeni. Ez lehet abszolút VAGY relatív URL-cím.
Lekérdezésparaméterek. request_query_parameter OR QueryParameters[request_query_parameter] A "request_query_parameter" felhasználó által definiált név, amely a következő HTTP-kérelem URL-címében egy lekérdezési paraméter nevére hivatkozik.
Fejlécek. request_header OR Headers[request_header] A "request_header" egy felhasználó által definiált név, 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érésben lezárja a lapozási ciklust.
MaxRequestNumber A lapozási kérelem maximális számát jelzi. Hagyja üresen, azt jelenti, hogy nincs korlát.
SupportRFC5988 Alapértelmezés szerint ez igaz értékre van állítva, ha nincs meghatározva lapozási szabály. Ezt a szabályt letilthatja, ha hamis értéket ad meg supportRFC5988 , vagy eltávolítja ezt a tulajdonságot a szkriptből.

A lapozási szabályokban támogatott értékek:

Érték Leírás
Fejlécek. response_header OR Headers[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 kiadásához lesz felhasználva.
Egy "$" kezdetű JSONPath-kifejezés (amely a választörzs gyökerét jelöli) A választörzsnek csak egy JSON-objektumot kell tartalmaznia. A JSONPath-kifejezésnek egyetlen primitív értéket kell visszaadnia, amelyet a rendszer a következő kérés kiadására fog használni.

Megjegyzés

A leképezési adatfolyamok lapozási szabályai eltérnek a másolási tevékenységekben a következő szempontokból:

  1. A tartomány nem támogatott a leképezési adatfolyamokban.
  2. [''] A nem támogatott az adatfolyamok leképezésében. Ehelyett a {} speciális karaktereket kell feloldani. 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 a másolási tevékenységben használttól. body A a válasz törzsét jelöli ahelyett, hogy $. header A helyett a válaszfejlécet headersjelöli. Íme két példa erre a különbségre:
    • 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 bemutatja a konfigurációs lépéseket, amelyek több kérést küldenek, 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: Adja meg sysparm_offset={offset} az alap URL-címet vagy a relatív URL-címet 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 AbsoluteUrlban

Ez a példa több kérelem küldésének konfigurációs lépéseit ismerteti, 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 a társított szolgáltatás konfigurációs oldalán található alap URL-címben , vagy az adathalmaz-kapcsolat panel relatív URL-címében .

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: A 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 bemutatja a konfigurációs lépéseket, amelyek több kérést küldenek, amelyek változói a 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-ás 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"-ként. 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 oszlopban találhatók, a záró vá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 paraméterben 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 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ítson be különböző zárófeltétel-szabályokat a különböző utolsó válaszok alapján. Lásd az alábbi példákat:

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

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

    {
        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 az adott csomópont válaszdózisban megadott értéke nem létezik

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

    {}
    

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

    Screenshot showing the End Condition setting for Example 4.2.

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

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

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

    Állítsa be a záró feltétel szabályát az "EndCondition:$" értékre. Complete": "Exist" (Létezik) 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 ér véget, ha a válaszban szereplő adott csomópont értéke egy felhasználó által megadott konstansé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ályát az "EndCondition:$" értékre. Complete": "Const:true" a lapozás befejezéséhez, ha a válaszban szereplő adott csomópont értéke egy felhasználó által megadott konstansérték.

    Screenshot showing the End Condition setting for Example 4.4.

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

    A REST API-válaszok fejléckulcsai az alábbi struktúrában láthatók:

    1. válaszfejléc: 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. Complete": "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 ér véget, ha a kulcs létezik a válaszfejlécben

    A REST API-válaszok fejléckulcsai az alábbi struktúrában láthatók:

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

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

    Screenshot showing the End Condition setting for Example 4.6.

5. példa: Záró felté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érelem küldésének konfigurációs lépéseit ismerteti, ha a tartományszabályt nem használják. A záró feltétel a 4.1-4.6-os 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, végtelen kéréseket küld a rendszer. A végfeltétel felhasználható a végtelen kérések elkerülésére. Ezért a zárófeltétel-szabály beállítása a 4.1-4.6. példára hivatkozik.

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

Állítsa be a MaxRequestNumber értéket, 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 törölheti 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 a leképezési adatfolyamokban, 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 .{ @odata.nextLink} null értékű 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 a végtelen hurokhoz vezet. A feltétel elkerüléséhez definiáljon zárófeltétel-szabályokat.

  • Ha az utolsó válasz értékeÜres, 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 last response is empty.

  • Ha a válaszfejlécben lévő teljes kulcs értéke true (igaz) értékű, a tördelé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 a leképezési adatfolyamokban, 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 megegyezik a 8. példában leírtaknak megfelelően, és az alábbi módon kell beállítani:

Screenshot showing setting the pagination rule for Example 9.

Az OAuth használata

Ez a szakasz azt ismerteti, hogyan másolhat adatokat a REST-összekötőből az OAuth használatával JSON formátumban Azure Data Lake Storage egy megoldássablon használatával.

A megoldássablon ismertetése

A sablon két tevékenységet tartalmaz:

  • A webes tevékenység lekéri a tulajdonosi jogkivonatot, majd átadja azt a későbbi Copy tevékenység hitelesítésként.
  • A másolási tevékenység adatokat másol a REST-ből a Azure Data Lake Storage.

A sablon két paramétert határoz meg:

  • A SinkContainer az a gyökérmappa elérési útja, ahová az adatok át lesznek másolva a Azure Data Lake Storage.
  • A SinkDirectory a gyökér alatti könyvtár elérési útja, ahová az adatok át lesznek másolva a Azure Data Lake Storage.

A megoldássablon használata

  1. Nyissa meg a MÁSOLÁS REST-ből vagy HTTP-ből OAuth-sablon használatával . Hozzon létre egy új kapcsolatot a forráskapcsolathoz. Create new connections

    Az alábbiakban az új társított szolgáltatás (REST) beállításainak főbb lépéseit találja:

    1. Az Alap URL-cím területen adja meg a saját forrás REST-szolgáltatásának URL-paraméterét.
    2. A hitelesítés típusaként válassza a Névtelen lehetőséget. New REST connection
  2. Hozzon létre egy új kapcsolatot a célkapcsolathoz.
    New Gen2 connection

  3. Válassza a Sablon használata lehetőséget. Use this template

  4. A létrehozott folyamat az alábbi példában látható módon jelenik meg: Screenshot shows the pipeline created from the template.

  5. Válassza ki a webes tevékenységet. A Gépház adja meg a megfelelő URL-címet, metódust, fejléceket és törzset az OAuth tulajdonosi jogkivonatának lekéréséhez annak a szolgáltatásnak a bejelentkezési API-jából, amelyből adatokat szeretne másolni. A sablon helyőrzője Azure Active Directory (AAD) OAuth-mintát mutat be. Vegye figyelembe, AAD REST-összekötő natív módon támogatja a hitelesítést, íme egy példa az OAuth-folyamatra.

    Tulajdonság Leírás
    URL-cím Adja meg az OAuth tulajdonosi jogkivonatának lekéréséhez tartozó URL-címet. például a mintában ez a https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/token
    Metódus A HTTP-metódus. Az engedélyezett értékek a Post és a Get.
    Fejlécek A fejléc felhasználó által definiált, amely egy fejlécnévre hivatkozik a HTTP-kérelemben.
    Törzs A HTTP-kérés törzse.

    Pipeline

  6. Az Adatmásolási tevékenységnél válassza a Forrás lapot, és láthatja, hogy az előző lépésből lekért tulajdonosi jogkivonat (access_token) a További fejlécek területen engedélyezésként át lesz adva az adatmásolási tevékenységnek. Folyamatfuttatás indítása előtt ellenőrizze a következő tulajdonságok beállításait.

    Tulajdonság Leírás
    Kérelem metódusa A HTTP-metódus. Az engedélyezett értékek a Beolvasás (alapértelmezett) és a Post.
    További fejlécek További HTTP-kérésfejlécek.

    Copy source Authentication

  7. Válassza a Hibakeresés lehetőséget, adja meg a paramétereket, majd kattintson a Befejezés gombra. Pipeline run

  8. Ha a folyamat futtatása sikeresen befejeződött, az alábbi példához hasonló eredményt fog látni: Pipeline run result

  9. Kattintson a WebActivity in Actions oszlop "Kimenet" ikonjára, ekkor megjelenik a szolgáltatás által visszaadott access_token.

    Token output

  10. Kattintson a CopyActivity in Actions oszlop "Bemenet" ikonjára. Ekkor a WebActivity által lekért access_token a rendszer átadja a CopyActivity-nek hitelesítés céljából.

    Token input

    Figyelemfelhívás

    Ha szeretné elkerülni, hogy a jogkivonatok egyszerű szövegben legyenek naplózva, engedélyezze a "Biztonságos kimenet" beállítást a webes tevékenységben, és a "Biztonságos bemenet" beállítást Copy tevékenység.

JSON-válasz exportálása aktuálisan

Ezzel a REST-összekötő használatával exportálhatja a REST API JSON-válaszait a különböző fájlalapú tárolókba. Az ilyen sémafüggetlen másolás eléréséhez hagyja ki az adathalmaz "struktúra" (más néven séma) szakaszát és a másolási tevékenység sémaleképezését.

Sémaleképezés

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

Következő lépések

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 a Azure Data Factory, olvassa el a Támogatott adattárak és formátumok című témakört.