Hostowanie punktów końcowych REST w konstruktorze interfejsu API danych

Artykuł
12/19/2024

Konstruktor interfejsu API danych udostępnia internetowy interfejs API RESTful, który umożliwia dostęp do tabel, widoków i procedur składowanych z połączonej bazy danych. Jednostki reprezentują obiekt bazy danych w konfiguracji środowiska uruchomieniowego konstruktora interfejsu API danych. Jednostka musi być ustawiona w konfiguracji środowiska uruchomieniowego, aby była dostępna w punkcie końcowym interfejsu API REST.

Wywoływanie metody interfejsu API REST

Aby odczytać lub zapisać w zasobie (lub jednostce), skonstruujesz żądanie przy użyciu następującego wzorca:

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

Nuta

Wszystkie składniki ścieżki adresu URL, w tym jednostki i parametry zapytania, są uwzględniane wielkość liter.

Składniki żądania obejmują:

	Opis
`{HTTP method}`	Metoda HTTP używana w żądaniu konstruktora interfejsu API danych
`{base_url}`	Domena (lub serwer localhost i port), który hostuje wystąpienie konstruktora interfejsu API danych
`{rest-path}`	Ścieżka podstawowa punktu końcowego interfejsu API REST ustawiona w konfiguracji środowiska uruchomieniowego
`{entity}`	Nazwa obiektu bazy danych zgodnie z definicją w konfiguracji środowiska uruchomieniowego

Oto przykładowe żądanie GET dla jednostki book znajdującej się na podstawie punktu końcowego REST /api w lokalnym środowisku deweloperskim localhost:

GET https:/localhost:5001/api/Book

Metody HTTP

Konstruktor interfejsu API danych używa metody HTTP w żądaniu, aby określić, jaką akcję należy wykonać dla wyznaczonej jednostki żądania. Dostępne są następujące czasowniki HTTP zależne od uprawnień ustawionych dla określonej jednostki.

Metoda	Opis
`GET`	Pobieranie zera, co najmniej jednego elementu
`POST`	Tworzenie nowego elementu
`PATCH`	Zaktualizuj element przy użyciu nowych wartości, jeśli istnieje. W przeciwnym razie utwórz nowy element
`PUT`	Zastąp element nowym elementem, jeśli istnieje. W przeciwnym razie utwórz nowy element
`DELETE`	Usuwanie elementu

Ścieżka rest

Ścieżka rest wyznacza lokalizację interfejsu API REST konstruktora interfejsu API danych. Ścieżka jest konfigurowana w konfiguracji środowiska uruchomieniowego i domyślnie ma wartość /api. Aby uzyskać więcej informacji, zobacz konfiguracja ścieżki REST.

Jednostka

Entity to terminologia używana do odwoływania się do zasobu interfejsu API REST w narzędziu Data API Builder. Domyślnie wartość trasy adresu URL dla jednostki to nazwa jednostki zdefiniowana w konfiguracji środowiska uruchomieniowego. Wartość ścieżki adresu URL REST jednostki jest konfigurowana w ustawieniach REST jednostki. Aby uzyskać więcej informacji, zobacz konfigurację jednostki .

Format zestawu wyników

Zwrócony wynik jest obiektem JSON o tym formacie:

{
    "value": []    
}

Elementy powiązane z żądaną jednostką są dostępne w tablicy value. Na przykład:

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

Nuta

Domyślnie zwracane są tylko pierwsze 100 elementów.

POBIERZ

Za pomocą metody GET można pobrać co najmniej jeden element żądanej jednostki.

Parametry adresu URL

Punkty końcowe REST umożliwiają pobieranie elementu przy użyciu klucza podstawowego przy użyciu parametrów adresu URL. W przypadku jednostek z pojedynczym kluczem podstawowym format jest prosty:

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

Aby pobrać książkę z identyfikatorem 1001, należy użyć:

GET /api/book/id/1001

W przypadku jednostek z kluczami podstawowymi złożonymi, w których do unikatowego identyfikowania rekordu jest używana więcej niż jedna kolumna, format adresu URL zawiera wszystkie kolumny klucza w sekwencji:

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

Jeśli jednostka books ma klucz złożony składający się z id1 i id2, należy pobrać określoną książkę w następujący sposób:

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

Na przykład:

Oto jak wygląda wywołanie:

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

Parametry zapytania

Punkty końcowe REST obsługują następujące parametry zapytania (wielkość liter), aby kontrolować zwrócone elementy:

$select: zwraca tylko wybrane kolumny
$filter: filtruje zwrócone elementy
$orderby: definiuje sposób sortowania zwracanych danych
$first i $after: zwraca tylko najważniejsze elementy n

Parametry zapytania mogą być używane razem.

`$select`

Parametr zapytania $select umożliwia określenie pól, które muszą być zwracane. Na przykład:

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

Nuta

Jeśli którekolwiek z żądanych pól nie istnieje lub nie jest dostępne z powodu skonfigurowanych uprawnień, zostanie zwrócony 400 - Bad Request.

Parametr zapytania $select, znany również jako "projekcja", służy do kontrolowania rozmiaru danych zwracanych w odpowiedzi interfejsu API. W przypadku tylko potrzebnych kolumn $select zmniejsza rozmiar ładunku, co może zwiększyć wydajność, minimalizując czas analizowania, zmniejszając użycie przepustowości i przyspieszając przetwarzanie danych. Ta optymalizacja rozszerza bazę danych. W tym miejscu są pobierane tylko żądane kolumny.

`$filter`

Wartość opcji $filter to wyrażenie predykatowe (wyrażenie zwracające wynik logiczny) wykorzystujące pola obiektu. Tylko elementy, w których wyrażenie daje wartość True, są uwzględniane w odpowiedzi. Na przykład:

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

Operatory obsługiwane przez opcję $filter to:

Operator	Typ	Opis	Przykład
`eq`	Porównanie	Równy	`title eq 'Hyperion'`
`ne`	Porównanie	Nie równa się	`title ne 'Hyperion'`
`gt`	Porównanie	Większe niż	`year gt 1990`
`ge`	Porównanie	Większe niż lub równe	`year ge 1990`
`lt`	Porównanie	Mniejsze niż	`year lt 1990`
`le`	Porównanie	Mniejsze niż lub równe	`year le 1990`
`and`	Logiczny	Logiczne i	`year ge 1980 and year lt 1990`
`or`	Logiczny	Logiczne lub	`year le 1960 or title eq 'Hyperion'`
`not`	Logiczny	Negacja logiczna	`not (year le 1960)`
`( )`	Grupowanie	Grupowanie pierwszeństwa	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Nuta

$filter jest argumentem z uwzględnieniem wielkości liter.

Parametr zapytania $filter w narzędziu Azure Data API Builder może przypominać niektórym użytkownikom usługi OData i dlatego, że był on bezpośrednio inspirowany możliwościami filtrowania OData. Składnia jest prawie identyczna, co ułatwia deweloperom, którzy znają już dane OData do pobierania i używania. Podobieństwo to było zamierzone, mające na celu zapewnienie znanego i zaawansowanego sposobu filtrowania danych między różnymi interfejsami API.

`$orderby`

Wartość parametru orderby jest rozdzielaną przecinkami listą wyrażeń używanych do sortowania elementów.

Każde wyrażenie w wartości parametru orderby może zawierać sufiks desc, aby poprosić o kolejność malejącą, oddzieloną od wyrażenia co najmniej jedną spacją.

Na przykład:

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

Nuta

$orderBy jest argumentem z uwzględnieniem wielkości liter.

Parametr zapytania $orderby jest przydatny do sortowania danych bezpośrednio na serwerze i jest również łatwe w obsłudze po stronie klienta. Jednak przydaje się w połączeniu z innymi parametrami zapytania, takimi jak $filter i $first. Parametr umożliwia stronicowanie zachowanie stabilnego i przewidywalnego zestawu danych podczas dzielenia się na strony za pośrednictwem dużych kolekcji.

`$first` i `$after`

Parametr zapytania $first ogranicza liczbę elementów zwracanych w jednym żądaniu. Na przykład:

GET /api/book?$first=5

To żądanie zwraca pierwsze pięć książek. Parametr zapytania $first w narzędziu Azure Data API Builder jest podobny do klauzuli TOP w języku SQL. Oba są używane do ograniczania liczby rekordów zwracanych z zapytania. Podobnie jak TOP w języku SQL umożliwia określenie ilości wierszy do pobrania, $first pozwala kontrolować liczbę elementów zwracanych przez interfejs API. $first jest przydatna, gdy chcesz pobrać mały podzbiór danych, taki jak pierwsze 10 wyników, bez pobierania całego zestawu danych. Główną zaletą jest wydajność, ponieważ zmniejsza ilość przesyłanych i przetwarzanych danych.

Nuta

W narzędziu Azure Data API builder liczba wierszy zwracanych domyślnie jest ograniczona przez ustawienie w pliku konfiguracji. Użytkownicy mogą zastąpić ten limit przy użyciu parametru $first w celu zażądania większej liczby wierszy, ale nadal istnieje skonfigurowana maksymalna liczba wierszy, które można zwrócić ogólnie. Ponadto istnieje limit całkowitej liczby megabajtów, które można zwrócić w jednej odpowiedzi, co jest również konfigurowalne.

Jeśli więcej elementów jest dostępnych poza określonym limitem, odpowiedź zawiera właściwość nextLink:

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

nextLink można użyć z parametrem zapytania $after w celu pobrania następnego zestawu elementów:

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

To podejście kontynuacji używa stronicowania opartego na kursorach. Unikatowy kursor to odwołanie do określonego elementu w zestawie danych, określając, gdzie kontynuować pobieranie danych w następnym zestawie. W przeciwieństwie do stronicowania indeksu, które używają przesunięć lub indeksów, stronicowanie oparte na kursorach nie polega na pomijaniu rekordów. Kontynuacja kursora sprawia, że jest bardziej niezawodny w przypadku dużych zestawów danych lub często zmienianych danych. Zamiast tego zapewnia płynny i spójny przepływ pobierania danych, zaczynając dokładnie tam, gdzie zostało przerwane ostatnie zapytanie, na podstawie podanego kursora.

Na przykład:

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

POST

Utwórz nowy element dla określonej jednostki. Na przykład:

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

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

Żądanie POST tworzy nową książkę. Należy podać wszystkie pola, które nie mogą mieć wartości null. Jeśli pełny obiekt jednostki zakończył się pomyślnie, w tym polami o wartości null, zostanie zwrócony:

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

KŁAŚĆ

FUNKCJA PUT tworzy lub zastępuje element określonej jednostki. Wzorzec zapytania to:

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

Na przykład:

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

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

Jeśli istnieje element z określonym kluczem podstawowym 2001, podane dane całkowicie zastępują tego elementu. Jeśli zamiast tego element o tym kluczu podstawowym nie istnieje, zostanie utworzony nowy element.

W obu przypadkach wynik wygląda następująco:

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

Nagłówek żądania HTTP `If-Match: *`

If-Match: * nagłówka HTTP zapewnia operacji aktualizacji jest wykonywana tylko wtedy, gdy zasób istnieje. Jeśli zasób nie istnieje, operacja zakończy się niepowodzeniem z kodem stanu HTTP: 404 Not Found. Jeśli nagłówek zostanie pominięty, domyślne zachowanie polega na wykonaniu upsert, co powoduje utworzenie zasobu, jeśli jeszcze nie istnieje.

Przykład:

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

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

Nuta

Jeśli określisz wartość inną niż * w nagłówku If-Match, konstruktor interfejsu API danych zwróci błąd 400 Bad Request, ponieważ dopasowanie na podstawie elementu ETag nie jest obsługiwane.

ŁATA

Funkcja PATCH tworzy lub aktualizuje element określonej jednostki. Dotyczy to tylko określonych pól. Nie ma to wpływu na wszystkie pola, które nie są określone w treści żądania. Jeśli element o określonym kluczu podstawowym nie istnieje, zostanie utworzony nowy element.

Wzorzec zapytania to:

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

Na przykład:

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

{    
  "year": 1991
}

Wynik wygląda następująco:

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

Nagłówek żądania HTTP `If-Match: *`

Przykład:

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

{
    "year": 1991
}

Nuta

USUNĄĆ

Funkcja DELETE usuwa element określonej jednostki. Wzorzec zapytania to:

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

Na przykład:

DELETE /api/book/id/2001

W przypadku powodzenia wynik jest pustą odpowiedzią z kodem stanu 204.

Transakcje bazy danych dla żądań interfejsu API REST

Przetwarzanie żądań interfejsu API POST, PUT, PATCH i DELETE; Konstruktor interfejsu API danych konstruuje i wykonuje zapytania bazy danych w transakcji.

W poniższej tabeli wymieniono poziomy izolacji, za pomocą których transakcje są tworzone dla każdego typu bazy danych.

Typ bazy danych	Poziom izolacji	Więcej informacji
Azure SQL (lub) SQL Server	Odczyt zatwierdzony	Azure SQL
MySQL	Powtarzalny odczyt	MySQL
PostgreSQL	Odczyt zatwierdzony	PostgreSQL

Udostępnij za pośrednictwem

Hostowanie punktów końcowych REST w konstruktorze interfejsu API danych

Wywoływanie metody interfejsu API REST

Metody HTTP

Ścieżka rest

Jednostka

Format zestawu wyników

POBIERZ

Parametry adresu URL

Na przykład:

Parametry zapytania

`$select`

`$filter`

`$orderby`

`$first` i `$after`

POST

KŁAŚĆ

Nagłówek żądania HTTP `If-Match: *`

ŁATA

Nagłówek żądania HTTP `If-Match: *`

USUNĄĆ

Transakcje bazy danych dla żądań interfejsu API REST

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Hostowanie punktów końcowych REST w konstruktorze interfejsu API danych

Wywoływanie metody interfejsu API REST

Metody HTTP

Ścieżka rest

Jednostka

Format zestawu wyników

POBIERZ

Parametry adresu URL

Na przykład:

Parametry zapytania

$select

$filter

$orderby

$first i $after

POST

KŁAŚĆ

Nagłówek żądania HTTP If-Match: *

ŁATA

Nagłówek żądania HTTP If-Match: *

USUNĄĆ

Transakcje bazy danych dla żądań interfejsu API REST

Powiązana zawartość

Opinia

Dodatkowe zasoby

`$select`

`$filter`

`$orderby`

`$first` i `$after`

Nagłówek żądania HTTP `If-Match: *`

Nagłówek żądania HTTP `If-Match: *`