Megosztás:

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

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 integrációs modul
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 változtatás nélkül, vagy dolgozza fel sémaleképezéssel. Csak a választerhelés támogatott JSON formátumban.

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 másolási tevékenység végrehajtásához egy folyamattal használhatja 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-cím A REST szolgáltatás alap URL-címe. Igen
szerver tanúsítvány ellenőrzésének engedélyezése 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)
hitelesítésTípusa 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 Egyéb HTTP-kérelemfejlécek 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"
        }
    }
}

Szolgáltatási főszereplő hitelesí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ő
szolgáltatási Főazonosító Adja meg a Microsoft Entra-alkalmazás ügyfél-azonosítóját. Igen
szolgáltatás-főazonosító-hiteltípus Adja meg a szolgáltatásfő hitelesítéshez használandó hitelesítőadat-típust. Az engedélyezett értékek: ServicePrincipalKey és ServicePrincipalCert. Nem
ServicePrincipalKey esetén
szolgáltatási főkulcs 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. Nem
Szolgáltatási Hitelesítő Tanúsítvány esetén
Beágyazott törzsszolgáltatás-certifikat Adja meg az alkalmazás Alap64 kódolású tanúsítványát, amelyet a Microsoft Entra ID-ban regisztráltak, és győződjön meg arról, hogy a tanúsítvány tartalomtípusa PKCS #12. Jelölje meg ezt a mezőt SecureStringként, hogy biztonságosan tárolja, vagy hivatkozzon az Azure Key Vaultban tárolt titkos kódra. Ebből a szakaszból megtudhatja, hogyan mentheti a tanúsítványt az Azure Key Vaultban. Nem
SzolgáltatásPrincipalBeágyazottTanúsítványJelszó Adja meg a tanúsítvány jelszavát, ha a tanúsítványt jelszó védi. Jelölje meg ezt a mezőt SecureStringként, hogy biztonságosan tárolja, vagy hivatkozzon az Azure Key Vaultban tárolt titkos kódra. Nem
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
Azure felhőtípus 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

1. példa: Szolgáltatás főkulcs hitelesítés használata

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

2. példa: Szolgáltatásfiók tanúsítvánnyal való hitelesítése

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

A szolgáltatásnév tanúsítványának mentése az Azure Key Vaultban

A szolgáltatásnév tanúsítványának mentésére két lehetősége van az Azure Key Vaultban:

  • 1\. lehetőség

    1. Konvertálja a szolgáltatásazonosító tanúsítványát egy base64 karakterláncra. További információ ebből a cikkből.

    2. Mentse a base64 sztringet titkos kódként az Azure Key Vaultban.

      Képernyőkép a titkokról.

      Képernyőkép a titkos kód értékéről.

  • 2 lehetőség

    Ha nem tudja letölteni a tanúsítványt az Azure Key Vaultból, ezzel a sablonnal titkos kódként mentheti a konvertált szolgáltatásnév-tanúsítványt az Azure Key Vaultban.

    Képernyőkép a sablonfolyamatról, amellyel titkos kulcsként mentheti a szolgáltatásnév tanúsítványát az AKV-ban.

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ó token végpontja a hozzáférési token megszerzéséhez. Igen
clientId Az alkalmazáshoz társított ügyfélazonosító. Igen
ügyféltitok 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ókör 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
azonosí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 beállította requestMethod, additionalHeaders, requestBody, és paginationRules az adathalmazban, a as-istovábbra is támogatott, miközben az új modell használata ajánlott a tevékenységek során előrehaladva.

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 Az HTTP módszer. Az engedélyezett értékek a GET (alapértelmezett) és a POST. Nem
továbbiFejlécek Egyéb HTTP-kérelemfejlécek. Nem
requestBody A HTTP-kérés törzse. Nem
lapozási szabályok 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
HTTP kérési időkorlát 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
kérésIntervallum 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 csak a JSON-válaszokat támogatja, automatikusan beállítja a fejlécet Accept: application/json.
A lapozás nem támogatott OLYAN REST API-válaszok esetében, ahol a legfelső szintű struktúra egy JSON-tömb.

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 Az HTTP módszer. Az engedélyezett értékek a POST (alapértelmezett), a PUT és a PATCH. Nem
továbbiFejlécek Egyéb HTTP-kérelemfejlécek. Nem
HTTP kérési időkorlát 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ának időtúllépése. Az alapértelmezett érték 00:01:40. Nem
kérésIntervallum 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
http-tömörítéstípus 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 Az HTTP módszer. 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
továbbiFejlécek Egyéb HTTP-kérelemfejlécek. Nem
HTTP kérési időkorlát 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ának időtúllépése. Az alapértelmezett érték 00:01:40. Nem
kérésIntervallum 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

Mosogató átalakítása

Tulajdonság Leírás Kötelező
továbbiFejlécek Egyéb HTTP-kérelemfejlécek. Nem
HTTP kérési időkorlát 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ának időtúllépése. Az alapértelmezett érték 00:01:40. Nem
kérésIntervallum 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
http-tömörítéstípus 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és, beszúrás, frissítés és upsert műveleteket, valamint a vonatkozó soradatokat a REST célhelyre a CRUD-műveletekhez való küldéshez.

Adatfolyam REST-fogadója

Adatfolyam-példaszkript

Figyelje meg, hogy a fogadó előtt egy módosítósor-átalakítás használatával utasíthatja az ADF-et, hogy milyen típusú műveletet hajtson végre a REST-fogadóval. Vagyis beszúrás, frissítés, felülírva beszúr, törlés.

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

Feljegyzés

Adatfolyam N-lapok feldolgozásakor összesen N+1 API-hívásokat generál. Ez magában foglal egy kezdeti hívást a séma következtetéséhez, amelyet a forrásból lekért lapok számának megfelelő N-hívások követnek.

Oldalazá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
  • A következő kérés fejléce = aktuális válasz fejlécekben lévő fejléc érték

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.
BefejezésiFeltétel: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.
MaximálisKérésekSzáma 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 egy 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. [''] nem támogatott az adatfolyamok leképezésében. Ehelyett használja a {}-t a speciális karakter elkerülésére. 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. A body a válasz törzsét jelzi, ahelyett hogy $ lenne használva. header a válasz fejlécének jelzésére szolgál headers helyett. Az alábbi két példa mutatja be ezt a különbséget:
    • 1. példa:
      Másolási tevékenység: "EndCondition:$.data": "Üres"
      Adatfolyamok leképezése: "EndCondition:body.data": "Empty"
    • 2. példa:
      Copy tevékenység: "EndCondition:headers.complete": "Létezik"
      Az 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 megadása vagy az sysparm_offset={offset}, vagy a 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: Adja meg a bemenetet akár az {id}-en a társított szolgáltatás konfigurációs lapján, akár a Relatív URL-en 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: Állítsa be a lapozási szabályokat úgy, hogy legyen "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
Request 1: Header(id->0)
Request 2: Header(id->10)
......
Request 100: Header(id->100)

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

2. lépés: Lapozási szabályok beállítása értéke "Fejlécek.{id}" : "RANGE: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 elküldéséhez, amelyek változói az AbsoluteUrl/QueryParameters/Headers függvényben 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
        }
    ]
}

Első lépés: Állítsa be a Lapozási szabályok tartományátpéldaként: Példa 1, és a tartomány végét hagyja üresen, így: "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ó Végállapot beállításáró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:$.Complete": "Exist" értékre, hogy a lapozás befejeződjön, amikor 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 következő zárófeltétel szabályt: "EndCondition:$.Complete": "Const:true", hogy a lapozás befejeződjön, amikor a válaszban szereplő adott csomópont értéke egy felhasználó által meghatározott konstans érték.

    Képernyőkép a 4.4-es példához tartozó Végfeltétel beállításáró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.Complete": "Const:1" értékre a lapozás befejezéséhez, amikor a válaszban szereplő fejléckulcs értéke megegyezik a felhasználó által megadott konstans é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ály nincs használatban. 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ályát a 4.1-4.6. példákra 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 supportRFC5988false 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.

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

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 {@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, amely a végfeltétel szabály beállítását mutatja: amikor a válaszfejlécben lévő teljes kulcs egyenlő igaz értékkel, azt jelzi, hogy a lapozás véget ér.

8b. példa: A következő kérés URL-címe a válasz törzsében található, amikor lapozást használ a másolási tevékenységben

Ez a példa bemutatja, hogyan állíthatja be a lapozási szabályt másolási tevékenységben, ha a következő kérés URL-címe a válasz törzsében található.

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

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

A lapozási szabályokat az alábbi képernyőképen látható módon kell beállítani:

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

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 változtatás nélkül

A REST-összekötővel exportálhatja a REST API JSON-válaszát as-is különböző fájlalapú tárolórendszerekbe (fogadókba). A sémától független másolási viselkedés engedélyezéséhez használja az alapértelmezett sémaleképezést (a Copy Activity Mapping lapján ne adjon meg leképezést.)

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.

  • Last updated on