Veri API'si oluşturucusunda REST uç noktalarını barındırma

Makale
08/14/2024

Veri API oluşturucusu, bağlı bir veritabanından tablolara, görünümlere ve saklı yordamlara erişmenizi sağlayan bir RESTful web API'sini sağlar. Varlıklar, Veri API'si oluşturucusunda çalışma zamanı yapılandırmasındaki bir veritabanı nesnesini temsil eder. Bir varlığın REST API uç noktasında kullanılabilir olması için çalışma zamanı yapılandırmasında ayarlanması gerekir.

REST API yöntemi çağırma

Kaynaktan (veya varlıktan) okumak veya bu kaynağa yazmak için aşağıdaki deseni kullanarak bir istek oluşturursunuz:

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

Not

Varlıklar ve sorgu parametreleri dahil olmak üzere URL yolunun tüm bileşenleri büyük/küçük harfe duyarlıdır.

İsteğin bileşenleri şunlardır:

	Açıklama
`{HTTP method}`	Veri API oluşturucusunun isteğinde kullanılan HTTP yöntemi
`{base_url}`	Veri API oluşturucusu örneğini barındıran etki alanı (veya localhost sunucusu ve bağlantı noktası)
`{rest-path}`	Çalışma zamanı yapılandırmasında ayarlanan REST API uç noktasının temel yolu
`{entity}`	Çalışma zamanı yapılandırmasında tanımlandığı gibi veritabanı nesnesinin adı

Aşağıda, localhostyerel geliştirme ortamındaKI REST uç nokta tabanı /api altında yer alan book varlığında bir GET isteği örneği verilmiştir:

GET https:/localhost:5001/api/Book

HTTP yöntemleri

Veri API oluşturucusu, istekte belirtilen varlıkta hangi eylemin gerçekleştirileceğini belirlemek için isteğinizdeki HTTP yöntemini kullanır. Belirli bir varlık için ayarlanan izinlere bağlı olarak aşağıdaki HTTP fiilleri kullanılabilir.

Yöntem	Açıklama
`GET`	Sıfır, bir veya daha fazla öğe alma
`POST`	Yeni öğe oluşturma
`PATCH`	Varsa bir öğeyi yeni değerlerle güncelleştirin. Aksi takdirde yeni bir öğe oluşturun
`PUT`	Varsa bir öğeyi yenisiyle değiştirin. Aksi takdirde yeni bir öğe oluşturun
`DELETE`	Öğe silme

Rest path

Geri kalan yol, Veri API'sinin oluşturucusunun REST API'sinin konumunu gösterir. Yol çalışma zamanı yapılandırmasında yapılandırılabilir ve varsayılan olarak /apiolarak ayarlanır. Daha fazla bilgi için bkz. REST yol yapılandırması.

Varlık

Entity, Veri API'sinin oluşturucusunda REST API kaynağına başvurmak için kullanılan terminolojidir. Varsayılan olarak, bir varlığın URL yol değeri çalışma zamanı yapılandırmasında tanımlanan varlık adıdır. Varlığın REST URL yolu değeri, varlığın REST ayarlarında yapılandırılabilir. Daha fazla bilgi için bkz. varlık yapılandırması.

Sonuç kümesi biçimi

Döndürülen sonuç şu biçime sahip bir JSON nesnesidir:

{
    "value": []    
}

İstenen varlıkla ilgili öğeler value dizisinde kullanılabilir. Mesela:

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

Not

Varsayılan olarak yalnızca ilk 100 öğe döndürülür.

AL

GET yöntemini kullanarak istenen varlığın bir veya daha fazla öğesini alabilirsiniz.

URL Parametreleri

REST uç noktaları, URL parametrelerini kullanarak bir öğeyi birincil anahtarına göre almanıza olanak sağlar. Tek bir birincil anahtara sahip varlıklar için biçim basittir:

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

1001kimliğine sahip bir kitabı almak için şunları kullanabilirsiniz:

GET /api/book/id/1001

Bir kaydı benzersiz olarak tanımlamak için birden fazla sütunun kullanıldığı bileşik birincil anahtarlara sahip varlıklar için URL biçimi tüm anahtar sütunlarını sırayla içerir:

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

bir books varlığı id1 ve id2'lerden oluşan bir bileşik anahtara sahipse, aşağıdaki gibi belirli bir kitabı alırsınız:

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

Mesela:

Arama şu şekilde görünür:

### 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

Sorgu parametreleri

REST uç noktaları, döndürülen öğeleri denetlemek için aşağıdaki sorgu parametrelerini (büyük/küçük harfe duyarlı) destekler:

$select: yalnızca seçili sütunları döndürür
$filter: döndürülen öğeleri filtreler
$orderby: Döndürülen verilerin nasıl sıralanacağını tanımlar
$first ve $after: yalnızca en üstteki n öğelerini döndürür

Sorgu parametreleri birlikte kullanılabilir.

`$select`

Sorgu parametresi $select döndürülecek alanları belirtmeye izin verir. Mesela:

### 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

Not

İstenen alanlardan herhangi biri yoksa veya yapılandırılmış izinler nedeniyle erişilebilir değilse, bir 400 - Bad Request döndürülür.

"projeksiyon" olarak da bilinen $select sorgu parametresi, API yanıtında döndürülen verilerin boyutunu denetlemek için kullanılır. Yalnızca gerekli sütunlarda $select yük boyutunu azaltır; bu da ayrıştırma süresini en aza indirerek, bant genişliği kullanımını azaltarak ve veri işlemeyi hızlandırarak performansı artırabilir. Bu iyileştirme veritabanına kadar uzanır. Burada, yalnızca istenen sütunlar alınır.

`$filter`

$filter seçeneğinin değeri, varlığın alanlarını kullanan bir koşul ifadesidir (boole sonucu döndüren bir ifade). Yanıta yalnızca ifadenin True olarak değerlendirildiği öğeler eklenir. Mesela:

### 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

$filter seçeneği tarafından desteklenen işleçler şunlardır:

Operatör	Tür	Açıklama	Örnek
`eq`	Karşılaştırma	Eşit	`title eq 'Hyperion'`
`ne`	Karşılaştırma	Eşit değil	`title ne 'Hyperion'`
`gt`	Karşılaştırma	Büyüktür	`year gt 1990`
`ge`	Karşılaştırma	Büyüktür veya eşittir	`year ge 1990`
`lt`	Karşılaştırma	Küçüktür	`year lt 1990`
`le`	Karşılaştırma	Küçük veya eşit	`year le 1990`
`and`	Mantıklı	Mantıksal ve	`year ge 1980 and year lt 1990`
`or`	Mantıklı	Mantıksal veya	`year le 1960 or title eq 'Hyperion'`
`not`	Mantıklı	Mantıksal olumsuzlama	`not (year le 1960)`
`( )`	Grup -landırma	Öncelik gruplandırma	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Not

$filter büyük/küçük harfe duyarlı bir bağımsız değişkendir.

Azure Data API Builder'daki $filter sorgu parametresi bazı kullanıcılara OData'yı anımsatabilir ve bunun nedeni doğrudan OData'nın filtreleme özelliklerinden esinlenmiş olmasıdır. Söz dizimi neredeyse aynıdır ve OData'yı zaten bilen geliştiricilerin alıp kullanmasını kolaylaştırır. Bu benzerlik, farklı API'lerde verileri filtrelemek için tanıdık ve güçlü bir yol sağlamaya yönelik kasıtlı olarak yapıldı.

`$orderby`

orderby parametresinin değeri, öğeleri sıralamak için kullanılan ifadelerin virgülle ayrılmış bir listesidir.

orderby parametre değerindeki her ifade, ifadeden bir veya daha fazla boşlukla ayrılmış bir azalan düzen istemek için sonek desc içerebilir.

Mesela:

### 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

Not

$orderBy büyük/küçük harfe duyarlı bir bağımsız değişkendir.

$orderby sorgu parametresi, verileri doğrudan sunucuda sıralamak ve istemci tarafında kolayca işlemek için değerlidir. Ancak, $filter ve $firstgibi diğer sorgu parametreleriyle birleştirildiğinde yararlı olur. parametresi, büyük koleksiyonlar arasında sayfalandırma yaptığınız sürece sayfalandırmanın kararlı ve öngörülebilir bir veri kümesini korumasını sağlar.

`$first` ve `$after`

$first sorgu parametresi, tek bir istekte döndürülen öğe sayısını sınırlar. Mesela:

GET /api/book?$first=5

Bu istek ilk beş kitabı döndürür. Azure Data API Builder'daki $first sorgu parametresi, SQL'deki TOP yan tümcesine benzer. Her ikisi de sorgudan döndürülen kayıt sayısını sınırlamak için kullanılır. SQL'deki TOP, alınacak satır sayısını belirtmenize olanak sağladığı gibi $first API tarafından döndürülen öğe sayısını denetlemenize olanak tanır. $first, veri kümesinin tamamını almadan ilk 10 sonuç gibi küçük bir veri alt kümesini getirmek istediğinizde kullanışlıdır. Ana avantaj, iletilen ve işlenen veri miktarını azalttığı için verimliliktir.

Not

Azure Data API oluşturucusunda, varsayılan olarak döndürülen satır sayısı yapılandırma dosyasındaki bir ayar ile sınırlıdır. Kullanıcılar daha fazla satır istemek için $first parametresini kullanarak bu sınırı geçersiz kılabilir, ancak yine de genel olarak döndürülebilecek en fazla satır sayısı yapılandırılmıştır. Ayrıca, tek bir yanıtta döndürülebilecek toplam megabaytlar için de yapılandırılabilir bir sınır vardır.

Belirtilen sınırın ötesinde daha fazla öğe varsa, yanıt bir nextLink özelliği içerir:

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

nextLink, sonraki öğe kümesini almak için $after sorgu parametresiyle kullanılabilir:

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

Bu devamlılık yaklaşımı, imleç tabanlı sayfalandırmayı kullanır. Benzersiz imleç, veri kümesindeki belirli bir öğeye yapılan başvurudur ve bir sonraki kümede veri almaya devam etmek için nereye karar verileceği belirlenir. Uzaklıkları veya dizinleri kullanan dizin sayfalandırmadan farklı olarak, imleç tabanlı sayfalandırma kayıtları atlamayı kullanmaz. İmleç devamı, büyük veri kümeleriyle veya sık sık değişen verilerle daha güvenilir olmasını sağlar. Bunun yerine, sağlanan imleç temelinde tam olarak son sorgunun kaldığı yerden başlayarak sorunsuz ve tutarlı bir veri alma akışı sağlar.

Mesela:

### 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}

YAYINLA

Belirtilen varlık için yeni bir öğe oluşturun. Mesela:

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

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

POST isteği yeni bir kitap oluşturur. Null değer atanamayan tüm alanlar sağlanmalıdır. Başarılı olursa, null alanlar da dahil olmak üzere tam varlık nesnesi döndürülür:

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

KOYMAK

PUT, belirtilen varlığın bir öğesini oluşturur veya değiştirir. Sorgu düzeni şöyledir:

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

Mesela:

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

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

2001belirtilen birincil anahtara sahip bir öğe varsa, sağlanan veriler bu öğenin tamamen değiştirilir. Bunun yerine bu birincil anahtara sahip bir öğe yoksa yeni bir öğe oluşturulur.

Her iki durumda da sonuç şöyle olur:

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

YAMA

PATCH, belirtilen varlığın öğesini oluşturur veya güncelleştirir. Yalnızca belirtilen alanlar etkilenir. İstek gövdesinde belirtilmeyen tüm alanlar etkilenmez. Belirtilen birincil anahtara sahip bir öğe yoksa yeni bir öğe oluşturulur.

Sorgu düzeni şöyledir:

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

Mesela:

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

{    
  "year": 1991
}

Sonuç şöyledir:

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

SİLMEK

DELETE, belirtilen varlığın öğesini siler. Sorgu düzeni şöyledir:

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

Mesela:

DELETE /api/book/id/2001

Başarılı olursa, sonuç 204 durum koduna sahip boş bir yanıttır.

REST API istekleri için veritabanı işlemleri

POST, PUT, PATCH ve DELETE API isteklerini işlemek için; Veri API'si oluşturucusu bir işlemdeki veritabanı sorgularını oluşturur ve yürütür.

Aşağıdaki tabloda, her veritabanı türü için işlemlerin oluşturulduğu yalıtım düzeyleri listelenir.

Veritabanı Türü	Yalıtım Düzeyi	Daha fazla bilgi
Azure SQL (veya) SQL Server	Okundu	Azure SQL
MySQL	Yinelenebilir Okuma	MySQL
PostgreSQL	Okundu	postgreSQL

OpenAPI
rest yapılandırma başvuru

Aracılığıyla paylaş

Veri API'si oluşturucusunda REST uç noktalarını barındırma

REST API yöntemi çağırma

HTTP yöntemleri

Rest path

Varlık

Sonuç kümesi biçimi

AL

URL Parametreleri

Mesela:

Sorgu parametreleri

`$select`

`$filter`

`$orderby`

`$first` ve `$after`

YAYINLA

KOYMAK

YAMA

SİLMEK

REST API istekleri için veritabanı işlemleri

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

Veri API'si oluşturucusunda REST uç noktalarını barındırma

REST API yöntemi çağırma

HTTP yöntemleri

Rest path

Varlık

Sonuç kümesi biçimi

AL

URL Parametreleri

Mesela:

Sorgu parametreleri

$select

$filter

$orderby

$first ve $after

YAYINLA

KOYMAK

YAMA

SİLMEK

REST API istekleri için veritabanı işlemleri

İlgili içerik

Geri Bildirim

Ek kaynaklar

`$select`

`$filter`

`$orderby`

`$first` ve `$after`