Salin dan ubah data dari dan ke titik akhir REST dengan menggunakan Azure Data Factory

BERLAKU UNTUK: Azure Data Factory Azure Synapse Analytics

Artikel ini menguraikan cara menggunakan Aktivitas Salin di Azure Data Factory untuk menyalin data dari dan ke titik akhir REST. Artikel ini dibuat berdasarkan Aktivitas Salin di Azure Data Factory, yang menyajikan gambaran umum Aktivitas Salin.

Perbedaan antara konektor REST, Konektor HTTP, dan Konektor tabel web adalah:

• Konektor REST secara khusus mendukung penyalinan data dari RESTful API.
• Konektor HTTP umumnya untuk mengambil data dari titik akhir HTTP apa pun, misalnya, untuk mengunduh file. Sebelum konektor REST ini, Anda mungkin menggunakan konektor HTTP untuk menyalin data dari RESTful API, yang didukung, tetapi kurang berfungsi dibandingkan dengan konektor REST.
• Konektor tabel web mengekstrak konten tabel dari halaman web HTML.

Kemampuan yang didukung

Konektor REST ini didukung untuk kemampuan berikut:

Kemampuan yang didukung	IR
Salin aktivitas (sumber/sink)	(1) (2)
Memetakan aliran data (sumber/sink)	(1)

① Runtime integrasi Azure ② Runtime integrasi yang dihost sendiri

Untuk mengetahui daftar penyimpanan data yang didukung sebagai sumber/sink, lihat Penyimpanan data yang didukung.

Secara khusus, konektor REST umum ini mendukung:

• Menyalin data dari titik akhir REST menggunakan metode GET atau POST dan menyalin data ke titik akhir REST menggunakan metode POST, PUT, atau PATCH.
• Menyalin data dengan menggunakan salah satu autentikasi berikut: Anonim, Dasar, Perwakilan Layanan, Kredensial Klien OAuth2, Identitas Terkelola yang Ditetapkan Sistem, dan Identitas Terkelola yang Ditetapkan Pengguna.
• Penomoran Halaman di REST API.
• Untuk REST sebagai sumber, menyalin respons REST JSON apa adanya atau mengurainya menggunakan pemetaan skema. Hanya payload respons di JSON yang didukung.

Prasyarat

Jika penyimpanan data Anda terletak di dalam jaringan lokal, jaringan virtual Azure, atau Amazon Virtual Private Cloud, Anda harus mengonfigurasi runtime integrasi yang dihosting sendiri untuk menghubungkannya.

Jika penyimpanan data Anda adalah layanan data cloud terkelola, Anda dapat menggunakan Azure Integration Runtime. Jika akses dibatasi untuk IP yang disetujui dalam aturan firewall, Anda dapat menambahkan IP Azure Integration Runtime ke daftar izinkan.

Anda juga dapat menggunakan fitur runtime integrasi jaringan virtual terkelola di Azure Data Factory untuk mengakses jaringan lokal tanpa menginstal dan mengonfigurasi runtime integrasi yang dihosting sendiri.

Untuk informasi selengkapnya tentang mekanisme dan opsi keamanan jaringan yang didukung oleh Data Factory, lihat Strategi akses data.

Memulai

Untuk melakukan aktivitas Salin dengan alur, Anda dapat menggunakan salah satu alat atau SDK berikut:

• Alat Penyalinan Data
• Portal Microsoft Azure
• SDK .NET
• SDK Python
• Azure PowerShell
• REST API
• Templat Azure Resource Manager

Membuat layanan yang tertaut dengan REST menggunakan UI

Gunakan langkah-langkah berikut untuk membuat layanan yang tertaut dengan REST di UI portal Microsoft Azure.

1. Telusuri ke tab Kelola di ruang kerja Azure Data Factory atau Synapse Anda dan pilih Layanan Tertaut, lalu pilih Baru:

   • Azure Data Factory
   • Azure Synapse

   

2. Cari REST dan pilih konektor REST.

   

3. Konfigurasikan detail layanan, uji koneksi, dan buat layanan tertaut baru.

   

Detail konfigurasi konektor

Bagian berikut menyediakan detail tentang properti yang dapat Anda gunakan untuk menentukan entitas Azure Data Factory khusus untuk konektor REST.

Properti layanan tertaut

Properti berikut didukung untuk layanan tertaut REST:

Properti	Deskripsi	Wajib
jenis	Properti jenis harus ditetapkan ke RestService.	Ya
url	URL dasar layanan REST.	Ya
enableServerCertificateValidation	Apakah memvalidasi sertifikat TLS/SSL sisi server saat menyambungkan ke titik akhir.	No (defaultnya adalah true)
authenticationType	Jenis autentikasi yang digunakan untuk menyambungkan ke layanan REST. Nilai yang diizinkan adalah Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential, dan ManagedServiceIdentity. Anda juga dapat mengonfigurasi header autentikasi di properti authHeaders. Lihat bagian terkait di bawah ini tentang properti dan contoh masing-masing selengkapnya.	Ya
authHeaders	Header permintaan HTTP tambahan untuk autentikasi. Misalnya, untuk menggunakan autentikasi kunci API, Anda dapat memilih jenis autentikasi sebagai "Anonymous" dan menentukan kunci API di header.	No
connectVia	Integration Runtime digunakan untuk menyambungkan ke penyimpanan data. Pelajari selengkapnya dari bagian Prasyarat. Jika tidak ditentukan, properti ini menggunakan Azure Integration Runtime default.	No

Untuk jenis autentikasi yang berbeda, harap lihat bagian terkait untuk detailnya.

• Autentikasi dasar
• Autentikasi Perwakilan Layanan
• Autentikasi Kredensial Klien untuk OAuth2
• Autentikasi identitas terkelola yang ditetapkan sistem
• Autentikasi identitas terkelola yang ditetapkan pengguna
• Autentikasi anonim

Menggunakan autentikasi dasar

Tetapkan properti authenticationType ke Dasar. Selain properti generik yang dijelaskan di bagian sebelumnya, atur properti berikut:

Properti	Deskripsi	Wajib diisi
userName	Nama pengguna yang digunakan untuk mengakses titik akhir REST.	Ya
kata sandi	Kata sandi untuk pengguna (nilai userName). Tandai bidang ini sebagai jenis SecureString untuk menyimpannya dengan aman di Azure Data Factory. Atau, Anda dapat mereferensikan rahasia yang disimpan di Azure Key Vault.	Ya

Contoh

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

Menggunakan autentikasi Perwakilan Layanan

Tetapkan properti authenticationType ke AadServicePrincipal. Selain properti generik yang dijelaskan di bagian sebelumnya, atur properti berikut:

Properti	Deskripsi	Wajib diisi
servicePrincipalId	Tentukan ID klien aplikasi Microsoft Entra.	Ya
servicePrincipalCredentialType	Jenis kredensial yang digunakan untuk autentikasi perwakilan layanan. Nilai yang diizinkan adalah ServicePrincipalKey dan ServicePrincipalCert.	No
Untuk ServicePrincipalKey
servicePrincipalKey	Tentukan kunci aplikasi Microsoft Entra. Tandai bidang ini sebagai SecureStringuntuk menyimpannya dengan aman di Azure Data Factory, atau rujuk rahasia yang disimpan di Azure Key Vault.	No
Untuk ServicePrincipalCert
servicePrincipalEmbeddedCert	Tentukan sertifikat yang dikodekan base64 dari aplikasi Anda yang terdaftar di ID Microsoft Entra, dan pastikan jenis konten sertifikat adalah PKCS #12. Tandai bidang ini sebagai SecureString untuk menyimpannya dengan aman, atau referensikan rahasia yang disimpan di Azure Key Vault. Buka bagian ini untuk mempelajari cara menyimpan sertifikat di Azure Key Vault.	No
servicePrincipalEmbeddedCertPassword	Tentukan kata sandi sertifikat Anda jika sertifikat Anda diamankan dengan kata sandi. Tandai bidang ini sebagai SecureString untuk menyimpannya dengan aman, atau referensikan rahasia yang disimpan di Azure Key Vault.	No
penyewa	Tentukan informasi penyewa (nama domain atau ID penyewa) tempat aplikasi Anda berada. Anda dapat mengambilnya dengan mengarahkan mouse ke sudut kanan atas portal Microsoft Azure.	Ya
aadResourceId	Tentukan sumber daya Microsoft Entra yang Anda minta untuk otorisasi, misalnya, https://management.core.windows.net.	Ya
azureCloudType	Untuk autentikasi Perwakilan Layanan, tentukan jenis lingkungan cloud Azure tempat aplikasi Microsoft Entra Anda terdaftar. Nilai yang diizinkan adalah AzurePublic, AzureChina, AzureUsGovernment, dan AzureGermany. Secara default, lingkungan cloud pabrik data digunakan.	No

Contoh 1: Menggunakan autentikasi kunci perwakilan layanan

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

Contoh 2: Menggunakan autentikasi sertifikat perwakilan layanan

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

Menyimpan sertifikat perwakilan layanan di Azure Key Vault

Anda memiliki dua opsi untuk menyimpan sertifikat perwakilan layanan di Azure Key Vault:

• Opsi 1

  1. Konversikan sertifikat perwakilan layanan menjadi string base64. Pelajari selengkapnya dari artikel ini.

  2. Simpan string base64 sebagai rahasia di Azure Key Vault.

     

     

• Opsi 2

  Jika Anda tidak dapat mengunduh sertifikat dari Azure Key Vault, Anda dapat menggunakan templat ini untuk menyimpan sertifikat perwakilan layanan yang dikonversi sebagai rahasia di Azure Key Vault.

  

Menggunakan autentikasi Kredensial Klien untuk OAuth2

Tetapkan properti authenticationType pada OAuth2ClientCredential. Selain properti generik yang dijelaskan di bagian sebelumnya, atur properti berikut:

Properti	Deskripsi	Wajib diisi
tokenEndpoint	Titik akhir token server otorisasi guna memperoleh token akses.	Ya
clientId	ID klien yang terkait pada aplikasi Zoho Anda.	Ya
clientSecret	Rahasia klien yang terkait pada aplikasi Square Anda. Tandai bidang ini sebagai jenis SecureString untuk menyimpannya dengan aman di Azure Data Factory. Atau, Anda dapat mereferensikan rahasia yang disimpan di Azure Key Vault.	Ya
cakupan	Lingkup akses yang dibutuhkan. Lingkup tersebut akan menjelaskan jenis akses apa yang diminta.	No
resource	Layanan atau sumber daya target di mana akses akan diminta.	No

Contoh

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

Menggunakan autentikasi identitas terkelola yang ditetapkan sistem

Tetapkan properti authenticationType ke ManagedServiceIdentity. Selain properti generik yang dijelaskan di bagian sebelumnya, atur properti berikut:

Properti	Deskripsi	Wajib diisi
aadResourceId	Tentukan sumber daya Microsoft Entra yang Anda minta untuk otorisasi, misalnya, https://management.core.windows.net.	Ya

Contoh

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

Menggunakan autentikasi identitas terkelola yang ditetapkan pengguna

Tetapkan properti authenticationType ke ManagedServiceIdentity. Selain properti generik yang dijelaskan di bagian sebelumnya, atur properti berikut:

Properti	Deskripsi	Wajib diisi
aadResourceId	Tentukan sumber daya Microsoft Entra yang Anda minta untuk otorisasi, misalnya, https://management.core.windows.net.	Ya
informasi masuk	Tentukan identitas terkelola yang ditetapkan pengguna sebagai objek kredensial.	Ya

Contoh

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

Menggunakan header autentikasi

Selain itu, Anda dapat mengonfigurasikan header permintaan untuk autentikasi bersama dengan jenis autentikasi bawaan.

Contoh: Menggunakan autentikasi kunci API

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

Properti himpunan data

Bagian ini menyediakan daftar properti yang didukung himpunan data REST.

Untuk daftar lengkap bagian dan properti yang tersedia untuk menentukan himpunan data, lihat Himpunan data dan layanan tertaut.

Untuk menyalin data dari REST, properti berikut didukung:

Properti	Deskripsi	Wajib
jenis	Properti jenis himpunan data harus diatur ke RestResource.	Ya
relativeUrl	URL relatif terhadap sumber daya yang berisi tabel. Jika properti ini tidak ditentukan, hanya URL yang ditentukan dalam definisi layanan tertaut yang digunakan. Konektor HTTP menyalin data dari URL gabungan: [URL specified in linked service]/[relative URL specified in dataset].	No

Jika Anda mengatur requestMethod, additionalHeaders, requestBody, dan paginationRules dalam himpunan data, ini masih didukung apa adanya, meskipun Anda disarankan untuk menggunakan model baru di sumber aktivitas ke depannya.

Contoh:

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

Properti Aktivitas Salin

Bagian ini menyediakan daftar properti yang didukung oleh sumber dan sink REST.

Untuk daftar lengkap bagian dan properti yang tersedia untuk menentukan aktivitas, lihat Alur.

REST sebagai sumber

Berikut ini properti yang didukung di bagian sumber aktivitas salin:

Properti	Deskripsi	Wajib
jenis	Properti jenis sumber aktivitas salinan harus diatur ke RestSource.	Ya
requestMethod	Metode HTTP. Nilai yang diizinkan adalah GET (default) dan POST.	No
additionalHeaders	Header permintaan HTTP tambahan.	No
requestBody	Isi untuk permintaan HTTP.	No
paginationRules	Aturan penomoran halaman untuk menyusun permintaan halaman berikutnya. Lihat bagian dukungan penomoran halaman untuk detailnya.	No
httpRequestTimeout	Waktu habis (nilai TimeSpan) untuk permintaan HTTP untuk mendapatkan respons. Nilai ini adalah batas waktu untuk mendapatkan respons, bukan batas waktu untuk membaca data respons. Nilai defaultnya adalah 00:01:40.	No
requestInterval	Waktu untuk menunggu sebelum mengirim permintaan untuk halaman berikutnya. Nilai default adalah00:00:01	No

Contoh 1: Menggunakan metode Get dengan penomoran halaman

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

Contoh 2: Menggunakan metode Post

"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 sebagai sink

Berikut adalah properti yang didukung di bagian sink aktivitas salin:

Properti	Deskripsi	Wajib
jenis	Properti jenis sink aktivitas salin harus diatur ke RestSink.	Ya
requestMethod	Metode HTTP. Nilai yang diizinkan adalah POST (default), PUT, dan PATCH.	No
additionalHeaders	Header permintaan HTTP tambahan.	No
httpRequestTimeout	Waktu habis (nilai TimeSpan) untuk permintaan HTTP untuk mendapatkan respons. Nilai ini adalah waktu habis untuk mendapatkan respons, bukan waktu habis untuk menulis data. Nilai defaultnya adalah 00:01:40.	No
requestInterval	Waktu interval di antara permintaan yang berbeda dalam milidetik. Nilai interval permintaan harus angka antara [10, 60000].	No
httpCompressionType	Jenis kompresi HTTP untuk digunakan saat mengirim data dengan Tingkat Kompresi Optimal. Nilai yang diizinkan adalah none dan gzip.	No
writeBatchSize	Jumlah catatan untuk ditulis ke sink REST per batch. Nilai default adalah 10000.	No

Konektor REST sebagai sink berfungsi dengan REST API yang menerima JSON. Data akan dikirim di JSON dengan pola berikut. Jika perlu, Anda dapat menggunakan pemetaan skema aktivitas salin untuk membentuk ulang data sumber agar sesuai dengan payload yang diharapkan REST API.

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

Contoh:

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

Properti pemetaan aliran data

REST didukung dalam aliran data untuk himpunan data integrasi dan himpunan data sejajar.

Transformasi sumber

Properti	Deskripsi	Wajib diisi
requestMethod	Metode HTTP. Nilai yang diperbolehkan adalah GET dan POST.	Ya
relativeUrl	URL relatif terhadap sumber daya yang berisi tabel. Jika properti ini tidak ditentukan, hanya URL yang ditentukan dalam definisi layanan tertaut yang digunakan. Konektor HTTP menyalin data dari URL gabungan: [URL specified in linked service]/[relative URL specified in dataset].	No
additionalHeaders	Header permintaan HTTP tambahan.	No
httpRequestTimeout	Waktu habis (nilai TimeSpan) untuk permintaan HTTP untuk mendapatkan respons. Nilai ini adalah waktu habis untuk mendapatkan respons, bukan waktu habis untuk menulis data. Nilai defaultnya adalah 00:01:40.	No
requestInterval	Waktu interval di antara permintaan yang berbeda dalam milidetik. Nilai interval permintaan harus angka antara [10, 60000].	No
QueryParameters.request_query_parameter ATAU QueryParameters['request_query_parameter']	"request_query_parameter" ditentukan pengguna, yang merujuk satu nama parameter kueri di URL permintaan HTTP berikutnya.	No

Transformasi sink

Properti	Deskripsi	Wajib diisi
additionalHeaders	Header permintaan HTTP tambahan.	No
httpRequestTimeout	Waktu habis (nilai TimeSpan) untuk permintaan HTTP untuk mendapatkan respons. Nilai ini adalah waktu habis untuk mendapatkan respons, bukan waktu habis untuk menulis data. Nilai defaultnya adalah 00:01:40.	No
requestInterval	Waktu interval di antara permintaan yang berbeda dalam milidetik. Nilai interval permintaan harus angka antara [10, 60000].	No
httpCompressionType	Jenis kompresi HTTP untuk digunakan saat mengirim data dengan Tingkat Kompresi Optimal. Nilai yang diizinkan adalah none dan gzip.	No
writeBatchSize	Jumlah catatan untuk ditulis ke sink REST per batch. Nilai default adalah 10000.	No

Anda dapat mengatur metode hapus, sisipkan, perbarui, dan upsert serta data baris relatif untuk dikirim ke sink REST untuk operasi CRUD.

Skrip aliran data sampel

Perhatikan penggunaan transformasi baris ubah sebelum sink untuk menginstruksikan ADF jenis tindakan apa yang harus diambil dengan sink REST Anda. Misalnya, menyisipkan, memperbarui, upsert, menghapus.

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

Dukungan penomoran halaman

Saat Anda menyalin data dari REST API, biasanya, REST API membatasi ukuran payload responsnya dari satu permintaan dengan jumlah yang wajar; sementara untuk mengembalikan data dalam jumlah besar, ia membagi hasilnya menjadi beberapa halaman dan mengharuskan penelepon mengirim permintaan berturut-turut untuk mendapatkan halaman hasil berikutnya. Biasanya, permintaan untuk satu halaman bersifat dinamis dan disusun oleh informasi yang dikembalikan dari respons halaman sebelumnya.

Konektor REST umum ini mendukung pola penomoran halaman berikut:

• URL absolut atau relatif permintaan berikutnya = nilai properti dalam isi respons saat ini
• URL absolut atau relatif permintaan berikutnya = nilai header dalam header respons saat ini
• Parameter kueri permintaan berikutnya = nilai properti dalam isi respons saat ini
• Parameter kueri permintaan berikutnya = nilai header dalam header respons saat ini
• Header permintaan berikutnya = nilai properti dalam isi respons saat ini
• Header kueri permintaan berikutnya = nilai header dalam header respons saat ini

Aturan penomoran halaman didefinisikan sebagai kamus dalam himpunan data, yang berisi satu atau beberapa pasangan nilai kunci peka huruf besar kecil. Konfigurasi akan digunakan untuk menghasilkan permintaan mulai dari halaman kedua. Konektor akan berhenti mengiterasi ketika mendapatkan kode status HTTP 204 (No Content), atau ekspresi JSONPath dalam "paginationRules" mengembalikan null.

Kunci yang didukung dalam aturan penomoran halaman:

Kunci	Deskripsi
AbsoluteUrl	Menunjukkan URL untuk mengeluarkan permintaan berikutnya. Ini bisa berupa URL absolut atau URL relatif.
QueryParameters.request_query_parameter ATAU QueryParameters['request_query_parameter']	"request_query_parameter" ditentukan pengguna, yang merujuk satu nama parameter kueri di URL permintaan HTTP berikutnya.
Headers.request_header ATAU Headers['request_header']	"request_header" ditentukan pengguna, yang merujuk satu nama header di permintaan HTTP berikutnya.
EndCondition:end_condition	"end_condition" didefinisikan oleh pengguna, yang menunjukkan kondisi yang akan mengakhiri perulangan penomoran halaman dalam permintaan HTTP berikutnya.
MaxRequestNumber	Menunjukkan nomor permintaan penomoran halaman maksimum. Jika dibiarkan kosong, berarti tidak ada batas yang ditetapkan.
SupportRFC5988	Secara default, ini diatur ke True jika tidak ada aturan penentuan halaman yang ditentukan. Anda dapat menonaktifkan aturan ini dengan mengatur supportRFC5988 ke False atau menghapus properti ini dari skrip.

Nilai yang didukung dalam aturan penomoran halaman:

Nilai	Deskripsi
Headers.response_header ATAU Headers['response_header']	"response_header" ditentukan pengguna, yang merujuk satu nama header dalam respons HTTP saat ini, yang nilainya akan digunakan untuk mengeluarkan permintaan berikutnya.
Ekspresi JSONPath dimulai dengan "$" (mewakili akar isi respons)	Isi respons hanya boleh berisi satu objek JSON dan array objek karena isi respons tidak didukung. Ekspresi JSONPath harus mengembalikan satu nilai primitif, yang akan digunakan untuk mengeluarkan permintaan berikutnya.

Contoh aturan penentuan halaman

Bagian ini menyediakan daftar contoh untuk seperangkat aturan penentuan halaman.

Contoh 1: Variabel dalam QueryParameters

Contoh ini menyediakan langkah-langkah konfigurasi untuk mengirim beberapa permintaan yang variabelnya ada di QueryParameters.

Beberapa permintaan:

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

Langkah 1: Masukkan sysparm_offset={offset} baik di URL Dasar atau URL Relatif seperti yang ditunjukkan pada cuplikan layar berikut:

or

Langkah 2: Tetapkan Aturan penentuan halaman sebagai opsi 1 atau opsi 2 :

• Opsi1: "QueryParameters.{ offset}" : "RANGE:0:10000:1000"

• Opsi2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

Contoh 2 : Variabel di AbsoluteUrl

Contoh ini menyediakan langkah-langkah konfigurasi untuk mengirim beberapa permintaan yang variabelnya ada di AbsoluteUrl.

Beberapa permintaan:

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

Langkah 1: Masukkan {id}baik di URL Dasar di halaman konfigurasi layanan tertaut atau URL Relatif di panel koneksi himpunan data.

or

Langkah 2: Tetapkan aturan Penentuan halaman sebagai "AbsoluteUrl.{ id}" :"RENTANG:1:100:1".

Contoh 3 : Variabel dalam Header

Contoh ini memberikan langkah-langkah konfigurasi untuk mengirim beberapa permintaan yang variabelnya ada di Header.

Beberapa permintaan:
PermintaanUrl: https://example/table
Permintaan 1: Header(id->0)
Permintaan 2: Header(id->10)
......
Permintaan 100: Header(id->100)

Langkah 1: Masukkan {id} di header Tambahan.

Langkah 2: Atur aturan Penomoran Halaman sebagai "Headers.{ id}" : "RANGE:0:100:10".

Contoh 4 : Variabel ada di AbsoluteUrl/QueryParameters/Headers, variabel akhir tidak ditentukan sebelumnya dan kondisi akhir didasarkan pada respons

Contoh ini menyediakan langkah-langkah konfigurasi untuk mengirim beberapa permintaan yang variabelnya ada di AbsoluteUrl/QueryParameters/Header tetapi variabel akhir tidak ditentukan. Untuk respons yang berbeda, pengaturan aturan kondisi akhir yang berbeda ditampilkan di Contoh 4.1-4.6.

Beberapa permintaan:

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

Dua tanggapan yang ditemui dalam contoh ini:

Respons 1:

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

Respons 2:

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

Langkah 1: Tetapkan rentang Aturan penentuan halaman sebagai Contoh 1 dan biarkan akhir rentang kosong sebagai "AbsoluteUrl.{offset}": "RANGE:0::1000".

Langkah 2: Tetapkan aturan kondisi akhir yang berbeda sesuai dengan respons terakhir yang berbeda. Lihat contoh berikut:

• Contoh 4.1: Penentuan halaman berakhir ketika nilai node tertentu dalam respons kosong

  REST API mengembalikan respons terakhir dalam struktur berikut:

  {
      Data: []
  }
  

  Atur aturan kondisi akhir sebagai "EndCondition:$.data": "Empty" untuk mengakhiri penentuan halaman ketika nilai node tertentu dalam respons kosong.

  

• Contoh 4.2: Penentuan halaman berakhir ketika nilai node tertentu dalam respons tidak ada

  REST API mengembalikan respons terakhir dalam struktur berikut:

  {}
  

  Set aturan kondisi akhir sebagai "EndCondition:$.data": "NonExist" untuk mengakhiri penentuan halaman saat nilai node tertentu dalam respons tidak ada.

  

• Contoh 4.3: Penentuan halaman berakhir ketika nilai node tertentu dalam respons ada

  REST API mengembalikan respons terakhir dalam struktur berikut:

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

  Atur aturan kondisi akhir sebagai "EndCondition:$. Complete": "Exist" untuk mengakhiri penentuan halaman ketika nilai node tertentu dalam respons ada.

  

• Contoh 4.4: Penentuan halaman berakhir ketika nilai node tertentu di dalam respons adalah nilai const yang ditentukan pengguna

  REST API mengembalikan respons dalam struktur berikut:

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

  ......

  Dan tanggapan terakhir adalah dalam struktur berikut:

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

  Set aturan kondisi akhir sebagai "EndCondition:$. Lengkap": "Const:true" untuk mengakhiri penentuan halaman ketika nilai node tertentu dalam respons adalah nilai const yang ditentukan pengguna.

  

• Contoh 4.5: Penentuan halaman berakhir ketika nilai kunci header dalam respons sama dengan nilai const yang ditentukan pengguna

  Kunci header dalam respons REST API ditampilkan dalam struktur berikut:

  Header respons 1: header(Complete->0)
  ......
  Header Respons terakhir: header(Complete->1)
  

  Set aturan kondisi akhir sebagai "EndCondition:headers.Complete": "Const:1" untuk mengakhiri penentuan halaman ketika nilai kunci header dalam respons sama dengan nilai const yang ditentukan pengguna.

  

• Contoh 4.6: Penentuan halaman berakhir ketika kunci ada di header respons

  Kunci header dalam respons REST API ditampilkan dalam struktur berikut:

  Header respons 1: header()
  ......
  Header Respons terakhir: header(CompleteTime->20220920)
  

  Set aturan kondisi akhir sebagai "EndCondition:headers. CompleteTime": "Exist"untuk mengakhiri penentuan halaman saat kunci ada di header respons.

  

Contoh 5 : Atur kondisi akhir untuk menghindari permintaan tanpa akhir saat aturan rentang tidak ditentukan

Contoh ini memberikan langkah konfigurasi untuk mengirim beberapa permintaan saat aturan rentang tidak digunakan. Kondisi akhir dapat diatur mengacu pada Contoh 4.1-4.6 untuk menghindari permintaan tanpa akhir. The REST API mengembalikan respons dalam struktur berikut, dalam hal ini URL halaman berikutnya disajikan di paging.next.

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

Jawaban terakhir adalah:

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

Langkah 1: Tetapkan Aturan penentuan halaman sebagai "AbsoluteUrl": "$.paging.next".

Langkah 2: Jika next dalam respons terakhir selalu sama dengan URL permintaan terakhir dan tidak kosong, permintaan tanpa akhir akan dikirim. Kondisi akhir dapat digunakan untuk menghindari permintaan tanpa akhir. Oleh karena itu, set aturan kondisi akhir mengacu pada Contoh 4.1-4.6.

Contoh 6: Atur jumlah permintaan maks untuk menghindari permintaan tanpa akhir

Atur MaxRequestNumber untuk menghindari permintaan tanpa akhir seperti yang ditunjukkan pada cuplikan layar berikut:

Contoh 7: Aturan penentuan halaman RFC 5988 didukung oleh default

Backend akan secara otomatis mendapatkan URL berikutnya berdasarkan link gaya RFC 5988 di header.

Contoh 8a: URL permintaan berikutnya ada di isi respons saat menggunakan penomoran halaman dalam pemetaan aliran data

Contoh ini menyatakan cara menetapkan aturan penentuan halaman dan aturan kondisi akhir dalam aliran data pemetaan saat URL permintaan berikutnya berasal dari isi respons.

Skema respons ditunjukkan di bawah ini:

Aturan penentuan halaman harus ditetapkan sebagai cuplikan layar berikut:

Secara default, penomoran halaman akan berhenti ketika isi. {@odata.nextLink}** null atau kosong.

Tetapi jika nilai @odata.nextLink di isi respons terakhir sama dengan URL permintaan terakhir, maka akan mengarah ke perulangan tanpa akhir. Untuk menghindari kondisi ini, tentukan aturan kondisi akhir.

• Jika Nilai dalam respons terakhir Kosong, maka aturan kondisi akhir dapat diatur seperti di bawah ini:

  

• Jika nilai kunci lengkap dalam header respons sama dengan True menunjukkan akhir penentuan halaman, maka aturan kondisi akhir dapat diatur seperti di bawah ini:

  

Contoh 8b: URL permintaan berikutnya ada di isi respons saat menggunakan penomoran halaman dalam aktivitas salin

Contoh ini menunjukkan cara mengatur aturan penomoran halaman dalam aktivitas salin saat URL permintaan berikutnya terkandung dalam isi respons.

Skema respons ditunjukkan di bawah ini:

Aturan penomoran halaman harus diatur seperti yang ditunjukkan pada cuplikan layar berikut:

Contoh 9: Format respons adalah XML dan URL permintaan berikutnya adalah dari isi respons saat menggunakan penentuan halaman dalam alilran data pemetaan

Contoh ini menyatakan cara mengatur aturan penentuan halaman dalam aliran data pemetaan saat format respons adalah XML dan URL permintaan berikutnya berasal dari isi respons. Seperti yang ditunjukkan pada cuplikan layar berikut, URL pertama adalah https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

Skema respons ditunjukkan di bawah ini:

Sintaks aturan penentuan halaman sama seperti di Contoh 8 dan harus diatur seperti contoh di bawah ini:

Ekspor respons JSON apa adanya

Anda dapat menggunakan konektor REST ini untuk mengekspor respons REST API JSON apa adanya ke berbagai penyimpanan berbasis file. Untuk mencapai salinan skema-agnostik seperti itu, lewati bagian "struktur" (juga disebut skema)dalam himpunan data dan pemetaan skema dalam aktivitas salin.

Pemetaan skema

Untuk menyalin data dari titik akhir REST ke sink tabular, lihat pemetaan skema.

Konten terkait

Untuk daftar penyimpanan data yang didukung Aktivitas Salin sebagai sumber dan sink di Azure Data Factory, lihat Penyimpanan data dan format yang didukung.