REST uç noktalarını çağırma

Veri API oluşturucusu (DAB), bağlı bir veritabanından tablolara, görünümlere ve saklı yordamlara erişmenizi sağlayan bir RESTful web API'sini sağlar. Kullanıma sunulan her veritabanı nesnesi, çalışma zamanı yapılandırmasında bir varlık olarak tanımlanır.

VARSAYıLAN olarak DAB, REST uç noktalarını şu konumda barındırıyor:

https://{base_url}/api/{entity}

Uyarı

Tüm yol bileşenleri ve sorgu parametreleri büyük/küçük harfe duyarlıdır.

Veri API'si oluşturucusunda desteklenen anahtar sözcükler

Konsept	REST	Amaç
Yansıtma	$select	Hangi alanların döndürüleceğini seçin
Filtering	$filter	Koşula bağlı olarak satırları kısıtlama
Sıralama	$orderby	Sıralama düzenini tanımlama
Sayfa Boyutu	$first	Sayfa başına öğeleri sınırlama
Devam	$after	Son sayfadan devam et

Temel yapı

REST API'yi çağırmak için şu deseni kullanarak bir istek oluşturun:

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

book varlığından tüm kayıtları okuma örneği:

GET https://localhost:5001/api/book

Yanıt, value dizisine sahip bir JSON nesnesidir. Sayfalandırma ve hata bilgileri yalnızca uygun olduğunda görünür.

Uyarı

Varsayılan olarak DAB, aksiruntime.pagination.default-page-size () yapılandırılmadığı sürece sorgu başına en fazla 100 öğe döndürür.

HTTP

GET https://localhost:5001/api/book

Başarı:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ]
}

Sayfalandırma ile başarı:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ],
  "nextLink": "https://localhost:5001/api/book?$after=WyJCb29rMiJd"
}

Boş sonuç (öğe bulunamadı):

{
  "value": []
}

Uyarı

Var olmayan bir birincil anahtar için GET isteği, boş bir value dizisiyle 200 OK döndürür, 404 Not Found döndürmez. Öğenin var olup olmadığını belirlemek için boş bir dizi olup olmadığını denetleyin.

cURL

curl -X GET "https://localhost:5001/api/book"

C#

Aşağıdaki model sınıfları DAB yanıtlarını seriden çıkartır:

using System.Text.Json.Serialization;

public class DabResponse<T>
{
    [JsonPropertyName("value")]
    public List<T>? Value { get; set; }

    [JsonPropertyName("nextLink")]
    public string? NextLink { get; set; }

    [JsonPropertyName("error")]
    public DabError? Error { get; set; }

    [JsonIgnore]
    public bool IsSuccess => Error is null;

    [JsonIgnore]
    public bool HasNextPage => NextLink is not null;
}

public class DabError
{
    [JsonPropertyName("code")]
    public string Code { get; set; } = string.Empty;

    [JsonPropertyName("message")]
    public string Message { get; set; } = string.Empty;

    [JsonPropertyName("status")]
    public int Status { get; set; }
}

public class Book
{
    [JsonPropertyName("id")]
    public int Id { get; set; }

    [JsonPropertyName("title")]
    public string Title { get; set; } = string.Empty;

    [JsonPropertyName("year")]
    public int? Year { get; set; }

    [JsonPropertyName("pages")]
    public int? Pages { get; set; }
}

API'yi çağırın ve yanıtı deserileştirin.

public async Task<List<Book>> GetBooksAsync()
{
    var response = await httpClient.GetAsync("api/book");
    response.EnsureSuccessStatusCode();
    var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

    if (result?.Error is not null)
    {
        throw new Exception($"{result.Error.Code}: {result.Error.Message}");
    }

    return result?.Value ?? [];
}

Python

Aşağıdaki veri sınıfları DAB yanıtlarını modellemektedir:

from dataclasses import dataclass
import requests

@dataclass
class Book:
    id: int
    title: str
    year: int | None = None
    pages: int | None = None

@dataclass
class DabError:
    code: str
    message: str
    status: int

@dataclass
class DabResponse:
    value: list[Book] | None = None
    next_link: str | None = None
    error: DabError | None = None

    @property
    def is_success(self) -> bool:
        return self.error is None

    @property
    def has_next_page(self) -> bool:
        return self.next_link is not None

API'yi çağırın ve yanıtı ayrıştırın:

def get_books(base_url: str) -> list[Book]:
    response = requests.get(f"{base_url}/api/book")
    response.raise_for_status()
    data = response.json()

    if "error" in data:
        err = data["error"]
        raise Exception(f"{err['code']}: {err['message']}")

    return [Book(**item) for item in data.get("value", [])]

JavaScript

Aşağıdaki işlev API'yi çağırır:

async function getBooks(baseUrl) {
  const response = await fetch(`${baseUrl}/api/book`);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  const data = await response.json();

  if (data.error) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }

  return data.value ?? [];
}

Örnek kullanım:

const books = await getBooks("https://localhost:5001");
console.log(`Fetched ${books.length} books from the API.`);

Sorgu türleri

Her REST varlığı hem koleksiyonu hem de tek kayıtlı okumaları destekler.

Operation	Açıklama
GET /api/{entity}	Kayıtların listesini döndürür
GET /api/{entity}/{primary-key-column}/{primary-key-value}	Birincil anahtara göre bir kayıt döndürür

Bir kayıt döndüren örnek:

GET /api/book/id/1010

Birçok değer döndüren örnek:

GET /api/book

Sonuçları filtreleme

Döndürülecek $filter kayıtları kısıtlamak için sorgu parametresini kullanın.

GET /api/book?$filter=title eq 'Foundation'

Bu sorgu, başlığı "Foundation" olan tüm kitapları döndürür.

Filtreler daha karmaşık sorgular için mantıksal işleçler içerebilir:

GET /api/book?$filter=year ge 1970 or title eq 'Dune'

Daha fazla bilgi için $filter değişken başvurusuna bakınız.

Sonuçları sıralama

parametresi kayıtların $orderby nasıl sıralanacağını tanımlar.

GET /api/book?$orderby=year desc, title asc

Bu, önce azalan düzende year ile ve ardından title ile sıralanmış kitapları geri döndürür.

Daha fazla bilgi için bkz. $orderby bağımsız değişken başvurusu.

Sonuçları sınırlandırma {#first-and-after}

$first parametresi, bir istekte kaç kaydın döndürülebileceğini sınırlar.

GET /api/book?$first=5

Bu, varsayılan olarak birincil anahtara göre sıralanmış ilk beş kitabı döndürür. Varsayılan olarak 100 öğe olan yapılandırılan en büyük sayfa boyutunu istemek için de kullanabilirsiniz $first=-1 . Bu sınırı runtime.pagination.default-page-size ile yapılandırma dosyanızda yapılandırın.

Daha fazla bilgi için bkz. $first bağımsız değişken referansı.

Devam eden sonuçlar

Sonraki sayfayı getirmek için, önceki yanıttan devam belirteci kullanarak $after kullanın.

GET /api/book?$first=5&$after={continuation-token}

Belirteç, $after son sorgunun nerede sona erdiği tanımlar. Daha fazla bilgi için $after argüman başvurusuna bakın.

Alan seçimi (projeksiyon)

Yanıta hangi alanların dahil olduğunu denetlemek için kullanın $select .

GET /api/book?$select=id,title,price

Bu yalnızca belirtilen sütunları döndürür. Bir alan eksikse veya erişilebilir değilse, DAB döndürür 400 Bad Request.

Daha fazla bilgi için bkz. $select bağımsız değişken başvurusu.

Verileri değiştirme

REST API, varlık izinlerine bağlı olarak oluşturma, güncelleştirme ve silme işlemlerini de destekler.

Yöntem	Eylem
POST	Yeni öğe oluşturma
PUT	Var olan bir öğeyi değiştirme (veya eksikse oluştur)
PATCH	Mevcut bir öğeyi güncelleştirme (veya eksikse oluşturma)
DELETE	Bir öğeyi birincil anahtara göre kaldırma

Önemli

PUT ve PATCH öğelerinin upsert (eksikse ekle) davranışı yalnızca veritabanı açık birincil anahtar değerlerine izin verdiğinde çalışır. Otomatik olarak oluşturulan anahtarlar (örneğin, SQL Server'daki IDENTITY sütunları veya PostgreSQL'deki SERIAL) bulunan tablolar için, var olmayan bir anahtara PUT veya PATCH ekleme girişimi 404 Not Found döndürür çünkü veritabanı, otomatik oluşturulan bir sütuna açık eklemeleri reddeder. Otomatik olarak oluşturulan anahtarlara sahip tablolarda kayıt oluşturmak için kullanın POST veya DAB'nin anahtarı otomatik olarak atamasına izin vermek için anahtarsız PUT ve PATCH kullanın.

Yeni bir kayıt oluştur

Yeni öğe oluşturmak için kullanın POST .

HTTP

POST https://localhost:5001/api/book
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

cURL

curl -X POST "https://localhost:5001/api/book" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

C#

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PostAsJsonAsync("api/book", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

Python

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.post(f"{base_url}/api/book", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

JavaScript

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Var olan kaydı güncelleştir

Mevcut bir öğedeki belirli alanları güncelleştirmek için kullanın PATCH .

HTTP

PATCH https://localhost:5001/api/book/id/2000
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

cURL

curl -X PATCH "https://localhost:5001/api/book/id/2000" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

C#

Tavsiye

VARSAYıLAN olarak, DAB istek gövdesinde veritabanında olmayan veya URL'ye ait olan alanları reddeder (PATCH ve DELETE için birincil anahtar alanları gibi). Bu davranış ayrı C# türleri gerektirir: biri POST anahtarları ve biri güncelleştirmeler için olmadan. Tüm işlemler için Book gibi tek bir türü yeniden kullanmak amacıyla, yapılandırmanızda runtime.rest.request-body-strict öğesini false olarak ayarlayın.

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PatchAsJsonAsync("api/book/id/2000", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

Python

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.patch(f"{base_url}/api/book/id/2000", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

JavaScript

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Kayıt silme

Bir öğeyi birincil anahtara göre kaldırmak için kullanın DELETE .

HTTP

DELETE https://localhost:5001/api/book/id/2000

cURL

curl -X DELETE "https://localhost:5001/api/book/id/2000"

C#

var response = await httpClient.DeleteAsync("api/book/id/2000");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

Python

response = requests.delete(f"{base_url}/api/book/id/2000")
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

JavaScript

const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "DELETE",
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Alt dizinleri olan gelişmiş REST yolları

Uyarı

Bu bölümde açıklanan Veri API oluşturucusu 2.0 işlevselliği şu anda önizleme aşamasındadır ve genel kullanılabilirlik öncesinde değişebilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

Varlık REST yolları, alt dizin stili URL kesimleri oluşturmak için ileri eğik çizgiler içerebilir. Bu yapılandırma, API'niz için daha etkileyici, hiyerarşik URL yapılarını etkinleştirir.

Varlığın rest.path özelliğinde bir alt dizin yolu yapılandırın:

{
  "entities": {
    "ShoppingCartItem": {
      "source": "dbo.ShoppingCartItem",
      "rest": {
        "path": "shopping-cart/item"
      }
    }
  }
}

Bu yapılandırma uç noktaya neden olur:

GET /api/shopping-cart/item

DAB, yönlendirmede en uzun önek eşleştirmesini kullandığı için daha belirli yollar, daha kısa olanlardan önce eşleştirilir. Güvenlik için doğrulama, yol geçişi desenlerini (örneğin ..), ters eğik çizgileri ve yüzde kodlanmış ayırıcıları engeller.

Daha fazla bilgi için bkz. REST yolu yapılandırması.

Otomatik olarak oluşturulan birincil anahtarlar için anahtarsız PUT ve PATCH

Uyarı

Bu bölümde açıklanan Veri API oluşturucusu 2.0 işlevselliği şu anda önizleme aşamasındadır ve genel kullanılabilirlik öncesinde değişebilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

Bir varlığın tüm birincil anahtar sütunları otomatik olarak oluşturulduğunda (örneğin SQL Server'daki IDENTITY sütunları), URL'de birincil anahtar belirtmeden PUT ve PATCH istekleri gönderebilirsiniz. DAB, ekleme sırasında anahtarı otomatik olarak atar.

PUT /api/Book
Content-Type: application/json

{
  "title": "My New Book",
  "publisher_id": 1234
}

Bu istek, otomatik olarak oluşturulan birincil anahtarla yeni Book bir kayıt oluşturur.

Anahtarsız işlemler için kurallar

• Atlanmış tüm birincil anahtar sütunları otomatik olarak oluşturulmalıdır. Atlanmış anahtar sütunu otomatik olarak oluşturulmazsa istek başarısız olur.
• Bileşik birincil anahtarlar için yine de URL'de anahtarın otomatik olarak oluşturulmamış bölümlerini sağlamanız gerekir.
• Saklı yordamlar bu özellikten etkilenmez. Kendi parametre işlemelerini kullanmaya devam ederler.
• OpenAPI belgesi, temel varlık yolundaki anahtarsız işlemleri (örneğin, PUT /api/Book anahtar segmentleri olmadan) yansıtır.

HTTP yanıt sıkıştırması

Uyarı

Bu bölümde açıklanan Veri API oluşturucusu 2.0 işlevselliği şu anda önizleme aşamasındadır ve genel kullanılabilirlik öncesinde değişebilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

DAB, yük boyutlarını azaltmak ve aktarım hızlarını artırmak için HTTP yanıt sıkıştırmasını destekler. Yapılandırma dosyanızın runtime.compression bölümünde sıkıştırmayı yapılandırın.

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Kullanılabilir sıkıştırma düzeyleri:

Seviye	Açıklama
optimal	Sıkıştırma oranını ve hızını dengeler (çoğu senaryo için önerilir)
fastest	Sıkıştırma hızının oran üzerinden önceliğini belirler
none	Sıkıştırmayı devre dışı bırakır

Sıkıştırmayı yapılandırma hakkında daha fazla bilgi için bkz. çalışma zamanı sıkıştırma yapılandırması.