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

  • Artikel

BERLAKU UNTUK:Azure Data Factory Azure Synapse Analytics

Tip

Cobalah Data Factory di Microsoft Fabric, solusi analitik all-in-one untuk perusahaan. Microsoft Fabric mencakup semuanya mulai dari pergerakan data hingga ilmu data, analitik real time, kecerdasan bisnis, dan pelaporan. Pelajari cara memulai uji coba baru secara gratis!

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.

Tip

Untuk menguji permintaan pengambilan data sebelum mengonfigurasi konektor REST di Azure Data Factory, pelajari tentang spesifikasi API untuk persyaratan header dan isi. Anda dapat menggunakan alat seperti Postman atau browser web untuk memvalidasi.

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:

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:

  2. Cari REST dan pilih konektor REST.

    Select REST connector.

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

    Configure REST linked service.

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.

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

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

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

Catatan

Konektor REST mengabaikan header "Terima" yang ditentukan di additionalHeaders. Karena konektor REST hanya mendukung respons di JSON, konektor ini akan secara otomatis menghasilkan header Accept: application/json.
Array objek sebagai isi respons tidak didukung dalam penomoran halaman.

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.

Data flow REST sink

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.

Catatan

Aturan penentuan halaman dalam aliran data pemetaan berbeda dengan aktivitas menyalin dalam aspek berikut:

  1. Rentang tidak didukung dalam aliran data pemetaan.
  2. [''] tidak didukung dalam aliran data pemetaan. Sebaliknya, gunakan {} untuk menghindari karakter khusus. Misalnya, body.{@odata.nextLink}, dengan node @odata.nextLink JSON-nya berisi karakter . khusus.
  3. Kondisi akhir didukung dalam aliran data pemetaan, tetapi sintaks kondisi berbeda dari itu dalam aktivitas menyalin. body digunakan untuk menunjukkan isi respons alih-alih $. header digunakan untuk menunjukkan header respons alih-alih headers. Berikut adalah dua contoh yang menunjukkan perbedaan ini:
    • Contoh 1:
      Aktivitas menyalin: "EndCondition:$.data": "Empty"
      Aliran data pemetaan: "EndCondition:body.data": "Empty"
    • Contoh 2:
      Aktivitas menyalin: "EndCondition:headers.complete": "Exist"
      Aliran data pemetaan: "EndCondition:header.complete": "Exist"

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:

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

or

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

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.

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

or

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

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: Tetapkan aturan Penentuan halaman sebagai "Headers.{ id}" : "RARNGE:0:100:10".

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

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.

    Screenshot showing the End Condition setting for Example 4.1.

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

    Screenshot showing the End Condition setting for Example 4.2.

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

    Screenshot showing the End Condition setting for Example 4.3.

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

    Screenshot showing the End Condition setting for Example 4.4.

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

    Screenshot showing the End Condition setting for Example 4.5.

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

    Screenshot showing the End Condition setting for Example 4.6.

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:

Screenshot showing the Max Request Number setting for Example 6.

Contoh 7: Aturan penentuan halaman RFC 5988 didukung oleh default

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

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

Tip

Jika Anda tidak ingin mengaktifkan aturan penentuan halaman default ini, Anda dapat mengatur supportRFC5988 ke false atau menghapusnya di skrip.

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

Contoh 8: URL permintaan berikutnya adalah dari isi respons saat menggunakan penentuan halaman dalam aliran data pemetaan

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:

Screenshot showing the response schema of Example 8.

Aturan penentuan halaman harus ditetapkan sebagai cuplikan layar berikut:

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

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:

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

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

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

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>

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

Skema respons ditunjukkan di bawah ini:

Screenshot showing the response schema of Example 9.

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

Screenshot showing setting the pagination rule for Example 9.

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.