Titik akhir REST host di penyusun API Data

Penyusun API Data menyediakan API web RESTful yang memungkinkan Anda mengakses tabel, tampilan, dan prosedur tersimpan dari database yang terhubung. Entitas mewakili objek database dalam konfigurasi runtime penyusun Api Data. Entitas harus diatur dalam konfigurasi runtime agar tersedia di titik akhir REST API.

Memanggil metode REST API

Untuk membaca dari atau menulis ke sumber daya (atau entitas), Anda membuat permintaan menggunakan pola berikut:

{HTTP method} https://{base_url}/{rest-path}/{entity}

Komponen permintaan meliputi:

Berikut adalah contoh permintaan GET pada entitas book yang berada di bawah titik akhir dasar REST /api dalam lingkungan pengembangan lokal localhost:

GET https:/localhost:5001/api/Book

Metode HTTP

Penyusun API Data menggunakan metode HTTP pada permintaan Anda untuk menentukan tindakan apa yang harus dilakukan pada entitas yang ditunjuk permintaan. Kata kerja HTTP berikut tersedia, tergantung pada izin yang ditetapkan untuk entitas tertentu.

Jalur istirahat

Jalur lainnya menunjuk lokasi REST API penyusun Data API. Jalur dapat dikonfigurasi dalam konfigurasi runtime dan secara default diatur ke /api. Untuk informasi selengkapnya, lihat konfigurasi jalur REST.

Entitas

Entity adalah terminologi yang digunakan untuk merujuk sumber daya REST API di Data API builder. Secara default, nilai rute URL untuk entitas adalah nama entitas yang ditentukan dalam konfigurasi runtime. Nilai jalur URL REST entitas dapat dikonfigurasi dalam pengaturan REST entitas. Untuk informasi lebih lanjut, lihat konfigurasi entitas .

Format tataan hasil

Hasil yang dikembalikan adalah objek JSON dengan format ini:

{
    "value": []    
}

Item yang terkait dengan entitas yang diminta tersedia dalam array value. Misalnya:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

DAPAT

Menggunakan metode GET, Anda dapat mengambil satu atau beberapa item entitas yang diinginkan.

Parameter URL

Titik akhir REST memungkinkan Anda mengambil item dengan kunci utamanya menggunakan parameter URL. Untuk entitas dengan satu kunci primer, formatnya mudah:

GET /api/{entity}/{primary-key-column}/{primary-key-value}

Untuk mengambil buku dengan ID 1001, Anda akan menggunakan:

GET /api/book/id/1001

Untuk entitas dengan kunci primer campuran, di mana lebih dari satu kolom digunakan untuk mengidentifikasi rekaman secara unik, format URL menyertakan semua kolom kunci secara berurutan:

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

Jika entitas books memiliki kunci gabungan yang terdiri dari id1 dan id2, Anda akan mendapatkan buku tertentu seperti ini:

GET /api/books/id1/123/id2/abc

Misalnya:

Berikut tampilan panggilan:

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

Parameter kueri

Titik akhir REST mendukung parameter kueri berikut (peka huruf besar/kecil) untuk mengontrol item yang dikembalikan:

• $select: hanya mengembalikan kolom yang dipilih
• $filter: memfilter item yang dikembalikan
• $orderby: menentukan bagaimana data yang dikembalikan diurutkan
• $first dan $after: hanya mengembalikan item n teratas

Parameter kueri dapat digunakan bersama-sama.

$select

Parameter kueri $select memungkinkan untuk menentukan bidang mana yang harus dikembalikan. Misalnya:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

Parameter kueri $select, juga dikenal sebagai "proyeksi", digunakan untuk mengontrol ukuran data yang dikembalikan dalam respons API. Dengan hanya kolom yang diperlukan, $select mengurangi ukuran payload, yang dapat meningkatkan performa dengan meminimalkan waktu penguraian, mengurangi penggunaan bandwidth, dan mempercepat pemrosesan data. Pengoptimalan ini meluas ke database. Di sana, hanya kolom yang diminta yang diambil.

$filter

Nilai opsi $filter adalah ekspresi predikat (sebuah ekspresi yang mengembalikan hasil boolean) yang menggunakan atribut entitas. Hanya item yang ekspresinya dievaluasi ke True yang disertakan dalam respons. Misalnya:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

Operator yang didukung oleh opsi $filter adalah:

Parameter kueri $filter di Azure Data API Builder mungkin mengingatkan beberapa pengguna OData, dan itu karena langsung terinspirasi oleh kemampuan pemfilteran OData. Sintaks hampir identik, memudahkan pengembang yang sudah terbiasa dengan OData untuk mengambil dan menggunakan. Kesamaan ini disengaja, bertujuan untuk menyediakan cara yang familier dan kuat untuk memfilter data di berbagai API.

$orderby

Nilai parameter orderby adalah daftar ekspresi yang dipisahkan koma yang digunakan untuk mengurutkan item.

Setiap ekspresi dalam nilai parameter orderby mungkin menyertakan akhiran desc untuk meminta urutan menurun, dipisahkan dari ekspresi oleh satu atau beberapa spasi.

Misalnya:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

Parameter kueri $orderby berharga untuk mengurutkan data langsung di server, mudah ditangani di sisi klien juga. Namun, ini menjadi berguna ketika dikombinasikan dengan parameter kueri lainnya, seperti $filter dan $first. Parameter memungkinkan penomoran halaman mempertahankan himpunan data yang stabil dan dapat diprediksi saat Anda mem-paginate melalui koleksi besar.

$first dan $after

Parameter kueri $first membatasi jumlah item yang dikembalikan dalam satu permintaan. Misalnya:

GET /api/book?$first=5

Permintaan ini mengembalikan lima buku pertama. Parameter kueri $first di Azure Data API Builder mirip dengan klausa TOP di SQL. Keduanya digunakan untuk membatasi jumlah rekaman yang dikembalikan dari kueri. Sama seperti TOP di SQL memungkinkan Anda menentukan kuantitas baris untuk diambil, $first memungkinkan Anda mengontrol jumlah item yang dikembalikan oleh API. $first berguna saat Anda ingin mengambil subset kecil data, seperti 10 hasil pertama, tanpa mengambil seluruh himpunan data. Keuntungan utamanya adalah efisiensi, karena mengurangi jumlah data yang dikirimkan dan diproses.

Jika lebih banyak item tersedia di luar batas yang ditentukan, respons menyertakan properti nextLink:

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

nextLink dapat digunakan dengan parameter kueri $after untuk mengambil kumpulan item berikutnya:

GET /api/book?$first={n}&$after={continuation-data}

Pendekatan kelanjutan ini menggunakan penomoran halaman berbasis kursor. Kursor unik adalah referensi ke item tertentu dalam himpunan data, menentukan tempat untuk terus mengambil data di set berikutnya. Tidak seperti penomoran halaman indeks yang menggunakan offset atau indeks, penomoran halaman berbasis kursor tidak bergantung pada melewatkan rekaman. Kelanjutan kursor membuatnya lebih andal dengan himpunan data besar atau data yang sering berubah. Sebaliknya, ini memastikan aliran pengambilan data yang lancar dan konsisten dengan memulai persis di mana kueri terakhir ditinggalkan, berdasarkan kursor yang disediakan.

Misalnya:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

TIANG

Buat item baru untuk entitas yang ditentukan. Misalnya:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

Permintaan POST membuat buku baru. Semua bidang yang tidak dapat diubah ke null harus disediakan. Jika berhasil objek entitas lengkap, termasuk bidang null apa pun, dikembalikan:

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

MELETAKKAN

PUT membuat atau mengganti item entitas yang ditentukan. Pola kueri adalah:

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

Misalnya:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Jika ada item dengan kunci utama yang ditentukan 2001, data yang disediakan sepenuhnya menggantikan item tersebut. Jika item dengan kunci utama tersebut tidak ada, item baru akan dibuat.

Dalam kedua kasus, hasilnya adalah sesuatu seperti:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

Header Permintaan HTTP If-Match: *

Header HTTP If-Match: * memastikan operasi pembaruan dilakukan hanya jika sumber daya ada. Jika sumber daya tidak ada, operasi akan gagal dengan Kode Status HTTP: 404 Not Found. Jika header If-Matchdihilangkan, perilaku defaultnya adalah melakukan upsert , yang membuat sumber daya jika belum ada.

Contoh :

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
  "title": "Stranger in a Strange Land",
  "pages": 525
}

PATCH

PATCH membuat atau memperbarui item entitas yang ditentukan. Hanya bidang yang ditentukan yang terpengaruh. Semua bidang yang tidak ditentukan dalam isi permintaan tidak terpengaruh. Jika item dengan kunci primer yang ditentukan tidak ada, item baru akan dibuat.

Pola kueri adalah:

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

Misalnya:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

Hasilnya seperti:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

Header Permintaan HTTP If-Match: *

Header HTTP If-Match: * memastikan operasi pembaruan dilakukan hanya jika sumber daya ada. Jika sumber daya tidak ada, operasi akan gagal dengan Kode Status HTTP: 404 Not Found. Jika header If-Matchdihilangkan, perilaku defaultnya adalah melakukan upsert , yang membuat sumber daya jika belum ada.

Contoh :

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

MENGHAPUS

DELETE menghapus item entitas yang ditentukan. Pola kueri adalah:

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

Misalnya:

DELETE /api/book/id/2001

Jika berhasil, hasilnya adalah respons kosong dengan kode status 204.

Transaksi database untuk permintaan REST API

Untuk memproses permintaan POST, PUT, PATCH, dan DELETE API; Penyusun API Data membuat dan menjalankan kueri database dalam transaksi.

Tabel berikut mencantumkan tingkat isolasi tempat transaksi dibuat untuk setiap jenis database.

Konten terkait

• OpenAPI
• referensi konfigurasi REST