DataWorks API data source - DataWorks - Alibaba Cloud Documentation Center

Anda dapat membuat REST API data source untuk menulis data JSON dari RESTful API ke sumber data lain, seperti MaxCompute, menggunakan task sinkronisasi. REST API data source juga dapat berfungsi sebagai tujuan untuk menerima data dari sumber data lain. Topik ini menjelaskan kemampuan sinkronisasi data REST API data source di DataWorks.

Batasan

Sumber data ini saat ini hanya mendukung Serverless resource groups dan exclusive resource groups for Data Integration.
Anda tidak dapat mengonfigurasi parameter timeout permintaan. Timeout permintaan bawaan di DataWorks adalah 60 detik. Jika kueri API Anda memerlukan waktu lebih dari 60 detik untuk mengembalikan respons, task akan gagal.

Tipe field yang didukung

Penting

Saat menyinkronkan data ke tujuan, hanya struktur tabel datar tingkat tunggal yang didukung. Struktur field bersarang tidak didukung. Misalnya, jika API mengembalikan struktur seperti {data: {user: { id: 1, name:'lily'}, value: 123}}, field tersebut harus diratakan menjadi kolom paralel seperti user_id, user_name, dan value di tujuan.

Type	Column type
Integer	LONG, INT
String	STRING
Floating-point	DOUBLE, FLOAT
Boolean	BOOLEAN
Date and time	DATE

Tambahkan sumber data

Sebelum mengembangkan task sinkronisasi di DataWorks, Anda harus menambahkan sumber data yang diperlukan ke DataWorks dengan mengikuti petunjuk dalam Data source management. Anda dapat melihat deskripsi parameter di Konsol DataWorks untuk memahami arti parameter saat menambahkan sumber data.

Otentikasi sumber data

REST API data source mendukung tiga metode otentikasi berikut:

No Auth: Tidak diperlukan otentikasi untuk mengakses API. Metode ini cocok untuk API publik.
Basic authentication: Menggunakan username dan password untuk otentikasi. Setelah memilih opsi ini, masukkan username dan password di UI konfigurasi.
Token-based authentication: Menggunakan token untuk otentikasi. Setelah memilih opsi ini, masukkan access token yang diperoleh dari API pihak ketiga ke dalam field Token di UI konfigurasi.

DataWorks tidak menyediakan alat bawaan untuk mendapatkan token dari API pihak ketiga. Jika API pihak ketiga Anda menggunakan metode otentikasi berbasis token seperti OAuth 2.0, Anda harus mendapatkan access token dari penyedia API tersebut. Perintah berikut menunjukkan contoh cara mendapatkan token:

curl -X POST https://api.example.com/oauth/token \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

Setelah mendapatkan token, atur authentication method ke Token-based authentication dan masukkan token tersebut ke dalam field yang sesuai saat menambahkan REST API data source.

Kembangkan task sinkronisasi

Untuk informasi tentang titik masuk dan prosedur konfigurasi task sinkronisasi, lihat panduan konfigurasi berikut.

Konfigurasi task offline tabel tunggal

Untuk petunjuknya, lihat codeless UI dan code editor.
Untuk daftar lengkap parameter dan demo skrip untuk code editor, lihat Lampiran: Demo skrip dan referensi parameter.

Contoh

FAQ

Apakah saya harus menentukan jumlah halaman yang diminta?
- J: Ya.
Apakah konektor mendukung paging otomatis, seperti berhenti ketika tidak ada data lagi yang dikembalikan?
- J: Tidak. Paging otomatis tidak didukung karena mencegah sistem membagi task secara benar.
Apa yang terjadi jika jumlah halaman yang ditentukan lebih besar daripada jumlah halaman aktual?
- J: Jika permintaan untuk suatu halaman mengembalikan data kosong, sistem memperlakukannya sebagai hasil kosong dan melanjutkan ke permintaan berikutnya. Task tidak gagal.
Apakah hanya mendukung penguraian data JSON tingkat tunggal?
- J: Ya, konektor tidak melakukan penguraian mendalam terhadap struktur bersarang.
Bagaimana cara mengonfigurasi Data Integration DataWorks untuk data non-array di REST API?
- J: Di bagian reader's parameter, atur dataPath ke path data non-array, misalnya dataPath:"data.list". Hal ini membantu plugin menemukan field data yang ingin Anda baca. Kemudian, atur dataMode ke multiData. Ini menginstruksikan DataWorks untuk memproses objek yang ditemukan sebagai kumpulan catatan individual, meskipun bukan array JSON.
  
  Catatan
  Dalam mode multiData, konfigurasi column diabaikan. Anda harus menentukan path data langsung di parameter dataPath.
  
  Kode berikut menunjukkan contoh konfigurasi untuk data non-array dari REST API:
```
reader: {
  name: "restapi",
  parameter: {
    dataPath: "data.list",
    dataMode: "multiData",
    // other parameters
  }
}
```

Lampiran: Demo skrip dan parameter

Konfigurasi task sinkronisasi batch menggunakan code editor

Jika Anda ingin mengonfigurasi task sinkronisasi batch menggunakan code editor, Anda harus mengonfigurasi parameter terkait dalam skrip berdasarkan persyaratan format skrip terpadu. Untuk informasi selengkapnya, lihat Configure with the Code Editor. Informasi berikut menjelaskan parameter yang harus Anda konfigurasi untuk sumber data saat mengonfigurasi task sinkronisasi batch menggunakan code editor.

Demo skrip reader

Kode berikut adalah contoh skrip:

{
    "type":"job",
    "version":"2.0",
    "steps":[
        {
            "stepType":"restapi",
            "parameter":{
                "url":"http://127.0.0.1:5000/get_array5",
                "dataMode":"oneData",
                "responseType":"json",
                "column":[
                    {
                        "type":"long",
                        "name":"a.b"  // Temukan data dari path a.b.
                    },
                    {
                        "type":"string",  // Temukan data dari path a.c.
                        "name":"a.c"
                    }
                ],
                "dirtyData":"null",
                "method":"get",
                "socketTimeout":"60000",
                "defaultHeader":{
                    "X-Custom-Header":"test header"
                },
                "customHeader":{
                    "X-Custom-Header2":"test header2"
                },
                "parameters":"abc=1&amp;def=1"
            },
            "name":"restapireader",
            "category":"reader"
        },
        {
            "stepType":"stream",
            "parameter":{

            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":""
        },
        "speed":{
            "throttle":true,  // Ketika throttle diatur ke false, parameter mbps diabaikan dan pembatasan kecepatan dinonaktifkan. Ketika throttle diatur ke true, pembatasan kecepatan diaktifkan.
            "concurrent":1,  // Konkurensi job.
            "mbps":"12"// Laju pembatasan. 1 mbps = 1 MB/s.
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Catatan untuk konfigurasi code editor:

Plugin REST API menerima badan respons JSON setelah mengirim permintaan HTTP atau HTTPS. Gunakan `dataPath` untuk menentukan JSONPath guna mengekstraksi data dari badan respons ini. Contoh:


Jika API mengembalikan badan respons di mana data bisnis berada di `DATA`, dan `DATA` adalah array berisi beberapa baris:
{
    "HEADER": {
        "BUSID": "bid1",
        "RECID": "uuid",
        "SENDER": "dc",
        "RECEIVER": "pre",
        "DTSEND": "202201250000"
    },
    "DATA": [
        {
            "SERNR": "sernr1"
        },
        {
            "SERNR": "sernr2"
        }
    ]
}

Untuk mengekstraksi beberapa baris dari `DATA` sebagai catatan sinkronisasi terpisah, atur `column` menjadi `"column": [ "SERNR" ]`, `dataMode` menjadi `"dataMode": "multiData"`, dan `dataPath` menjadi `"dataPath": "DATA"`.


Jika API mengembalikan badan respons di mana data bisnis berada di `content.DATA`, dan `DATA` adalah objek tunggal:
{
    "HEADER": {
        "BUSID": "bid1",
        "RECID": "uuid",
        "SENDER": "dc",
        "RECEIVER": "pre",
        "DTSEND": "202201250000"
    },
    "content": {
        "DATA": {
            "SERNR": "sernr2"
        }
    }
}

Untuk mengekstraksi satu baris dari `content.DATA` sebagai satu catatan sinkronisasi, atur `column` menjadi `"column": [ "SERNR" ]`, `dataMode` menjadi `"dataMode": "oneData"`, dan `dataPath` menjadi `"dataPath": "content.DATA"`.

Parameter skrip reader

Catatan

Parameter berikut dapat dikonfigurasi saat Anda menambahkan sumber data dan mengonfigurasi node Data Integration.

Plugin ini tidak mendukung parameter penjadwalan.

Parameter	Deskripsi	Wajib	Bawaan
url	Alamat RESTful API.	Ya	Tidak ada
dataMode	Menentukan cara menafsirkan data JSON dalam respons API. oneData: Respons, atau objek di `dataPath`, diperlakukan sebagai satu catatan data. multiData: Respons, atau objek di `dataPath`, diperlakukan sebagai array JSON di mana setiap elemen merupakan catatan data terpisah.	Ya	Tidak ada
responseType	Format data respons. Saat ini hanya format JSON yang didukung.	Ya	JSON
column	Daftar field yang akan dibaca. `type` menentukan tipe data sumber, dan `name` menentukan JSONPath untuk data field tersebut. Contoh: `[{"type": "long", "name": "a.b"}, {"type": "string", "name": "a.c"}]` Parameter `type` dan `name` wajib untuk setiap kolom yang Anda tentukan.	Ya	Tidak ada
dataPath	Path ke objek JSON tunggal atau array JSON dalam respons.	Tidak	Tidak ada
method	Metode permintaan. Nilai yang valid: GET dan POST.	Ya	Tidak ada
socketTimeout	Timeout socket untuk permintaan API, dalam milidetik.	Tidak	60000
customHeader	Header kustom yang disertakan dalam permintaan API.	Tidak	Tidak ada
parameters	Informasi parameter yang diteruskan ke RESTful API. Untuk metode GET, masukkan parameter dalam format `abc=1&def=1`. Untuk metode POST, masukkan parameter dalam format JSON.	Tidak	Tidak ada
dirtyData	Menentukan cara menangani catatan di mana data field tidak ditemukan pada JSONPath yang ditentukan. dirty: Jika field tidak ditemukan, seluruh catatan diperlakukan sebagai data kotor. null: Jika field tidak ditemukan, nilainya diatur ke `null` dalam catatan output.	Ya	dirty
requestTimes	Menentukan apakah akan mengirim satu permintaan atau beberapa permintaan. single: Satu permintaan dikirim. multiple: Beberapa permintaan dikirim.	Ya	single
requestParam	Saat `requestTimes` bernilai `multiple`, parameter ini menentukan nama parameter permintaan yang digunakan untuk looping (misalnya, `pageNumber`). Plugin melakukan iterasi dari `startIndex` ke `endIndex` dengan `step` tertentu, mengirim permintaan untuk setiap nilai.	Tidak	Tidak ada
startIndex	Nilai awal untuk parameter loop yang ditentukan di `requestParam`. Nilai ini inklusif.	Tidak	Tidak ada
endIndex	Nilai akhir untuk parameter loop. Nilai ini inklusif.	Tidak	Tidak ada
step	Nilai increment untuk setiap langkah dalam loop.	Tidak	Tidak ada
authType	Metode otentikasi. Nilai yang valid: Basic Auth: Otentikasi dasar. Jika API sumber data mendukung otentikasi dengan username dan password, pilih metode ini. Kemudian, konfigurasikan username dan password. Selama integrasi data, kredensial dikirim ke titik akhir RESTful melalui protokol Basic Auth untuk otentikasi. Token Auth: Otentikasi berbasis token. Jika API sumber data mendukung otentikasi berbasis token, pilih metode ini. Kemudian, konfigurasikan nilai token tetap. Selama integrasi data, token diteruskan dalam header permintaan untuk otentikasi. Contoh: {"Authorization":"Bearer TokenXXXXXX"}. Catatan Untuk menggunakan metode enkripsi kustom, Anda dapat menggunakan metode otentikasi `Token` dan memberikan informasi otentikasi terenkripsi sebagai `AuthToken`.	Tidak	Tidak ada
authUsername/authPassword	Username dan password untuk otentikasi Basic.	Tidak	Tidak ada
authToken	Token untuk otentikasi berbasis token.	Tidak	Tidak ada
accessKey/accessSecret	Informasi akun untuk verifikasi signature API Aliyun.	Tidak	Tidak ada

Demo skrip writer

{
    "type":"job",
    "version":"2.0",
    "steps":[
        {
            "stepType":"stream",
            "parameter":{

            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"restapi",
            "parameter":{
                "url":"http://127.0.0.1:5000/writer1",
                "dataMode":"oneData",
                "responseType":"json",
                "column":[
                    {
                        "type":"long", // Tempatkan data kolom di path a.b.
                        "name":"a.b"
                    },
                    {
                        "type":"string", // Tempatkan data kolom di path a.c.
                        "name":"a.c"
                    }
                ],
                "method":"post",
                "defaultHeader":{
                    "X-Custom-Header":"test header"
                },
                "customHeader":{
                    "X-Custom-Header2":"test header2"
                },
                "parameters":"abc=1&amp;def=1",
                "batchSize":256
            },
            "name":"restapiwriter",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0" // Jumlah catatan error.
        },
        "speed":{
            "throttle":true, // Ketika throttle diatur ke false, parameter mbps diabaikan dan pembatasan kecepatan dinonaktifkan. Ketika throttle diatur ke true, pembatasan kecepatan diaktifkan.
            "concurrent":1, // Konkurensi job.
            "mbps":"12" // Laju pembatasan. 1 mbps = 1 MB/s.
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Parameter skrip writer

Parameter	Deskripsi	Wajib	Bawaan
url	Alamat RESTful API.	Ya	Tidak ada
dataMode	Format data JSON yang diteruskan dalam permintaan RESTful. oneData: Setiap catatan data dikirim dalam permintaan API terpisah. multiData: Catatan data dikelompokkan menjadi batch, dan setiap batch dikirim sebagai array JSON dalam satu permintaan API. Ukuran batch dikonfigurasi oleh parameter batchSize.	Ya	Tidak ada
column	Daftar path field untuk data JSON yang dihasilkan. type menentukan tipe data sumber, dan name menentukan JSONPath tempat meletakkan data untuk kolom saat ini. Contoh: `[{"type":"long", "name":"a.b"}, {"type":"string", "name":"a.c"}]` Catatan Parameter `type` dan `name` wajib untuk setiap kolom yang Anda tentukan.	Ya	Tidak ada
dataPath	Path objek JSON tempat data ditempatkan.	Tidak	Tidak ada
method	Metode permintaan. Nilai yang valid: POST dan PUT.	Ya	Tidak ada
customHeader	Informasi header yang diteruskan ke RESTful API.	Tidak	Tidak ada
authType	Metode otentikasi. Basic Auth: Otentikasi dasar. Jika API sumber data mendukung otentikasi dengan username dan password, pilih metode ini. Kemudian, konfigurasikan username dan password. Selama integrasi data, kredensial dikirim ke titik akhir RESTful melalui protokol Basic Auth untuk otentikasi. Token Auth: Otentikasi berbasis token. Jika API sumber data mendukung otentikasi berbasis token, pilih metode ini. Kemudian, konfigurasikan nilai token tetap. Selama integrasi data, token diteruskan dalam header permintaan untuk otentikasi. Contoh: {"Authorization":"Bearer TokenXXXXXX"}. Catatan Untuk menggunakan metode enkripsi kustom, Anda dapat menggunakan metode otentikasi `Token` dan memberikan informasi otentikasi terenkripsi sebagai `AuthToken`.	Tidak	Tidak ada
authUsername/authPassword	Username dan password untuk otentikasi Basic.	Tidak	Tidak ada
authToken	Token untuk otentikasi berbasis token.	Tidak	Tidak ada
accessKey/accessSecret	Informasi akun untuk verifikasi signature API Aliyun.	Tidak	Tidak ada
batchSize	Saat `dataMode` bernilai `multiData`, parameter ini menentukan jumlah maksimum catatan yang disertakan dalam satu batch permintaan.	Ya	512