Używanie nagłówka HTTP If-Match w operacjach PUT i PATCH

W przypadku punktów końcowych REST deweloperzy często chcą kontrolować, czy aktualizacje tworzą nowe rekordy, czy modyfikują tylko istniejące. Nagłówek HTTP udostępnia kontrolkę w narzędziu If-Match Data API Builder (DAB).

Domyślnie daB traktuje operacje PUT upsert i PATCH jako operacje upsert :

  • Jeśli zasób istnieje: program DAB go aktualizuje.

  • Jeśli nie istnieje: program DAB wstawia go.

    • PUT → pełnej operacji upsert (zastępuje zasób).
    • PATCH → przyrostowe upsert (stosuje częściową aktualizację).

Dodawanie If-Match: * zmian tego zachowania do semantyki tylko aktualizacji.

Co If-Match robi w języku DAB

If-Match jest obsługiwany tylko w przypadku wartości *wieloznacznych .

Wartość nagłówka Zachowanie
If-Match: * Przeprowadź aktualizację tylko wtedy, gdy zasób istnieje; jeśli brakuje → 404 Nie znaleziono.
If-Match: <any other> Odrzucone; 400 Nieprawidłowe żądanie (Etags not supported, use '*').
(nieobecny) Zachowanie operacji upsert (wstaw, jeśli nie znaleziono, w przeciwnym razie zaktualizuj).

Omówienie zachowania

  • Język DAB nie implementuje elementu ETag dla rekordu ani dopasowania wersji.
  • Nie ocenia się tokenu współbieżności. * tylko asercyjnie "musi istnieć".
  • Dotyczy tylko rest, a nie GraphQL.
  • Obecnie nie ma znaczenia dla operacji DELETE.

Używanie If-Match z funkcją PUT

Bez If-Matchmetody funkcja PUT wstawia, gdy zasób nie istnieje (zwraca wartość 201 Created).

Przykład tylko do aktualizacji

Ważna

Ponieważ PUT wykonuje pełne zastąpienie, treść żądania musi zawierać wszystkie kolumny niepuste. Pominięcie wymaganej kolumny powoduje 400 Bad Request błąd bazy danych, nawet jeśli If-Match: * jest obecny. Użyj PATCH zamiast PUT , jeśli chcesz wysłać tylko podzbiór pól.

Żądanie

PUT /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Return of the King",
  "publisher_id": 7
}

Powodzenie (rekord istniał)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Return of the King",
  "publisher_id": 7
}

Błąd (brak rekordu)

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Przykład wstawiania upsert (nie If-Match i rekord nie istnieje)

Żądanie

PUT /api/Books/id/500
Content-Type: application/json

{
  "title": "Inserted via PUT",
  "publisher_id": 7
}

Odpowiedź

HTTP/1.1 201 Created
Location: id/500
Content-Type: application/json

{
  "id": 500,
  "title": "Inserted via PUT",
  "publisher_id": 7
}

Używanie If-Match z poprawką PATCH

PATCH zachowuje się podobnie. Bez If-Matchparametru wykonuje przyrostowe operacje upsert. W programie If-Match: *aktualizuje tylko istniejące wiersze.

Żądanie

PATCH /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Two Towers"
}

Odpowiedź w przypadku powodzenia

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Two Towers"
}

Odpowiedź, gdy nie znaleziono

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Nieprawidłowe użycie If-Match

Każda wartość inna niż * (w tym ciągi cytowane) jest odrzucana.

Żądanie

PUT /api/Books/id/1
If-Match: "abc123"
Content-Type: application/json

{
  "title": "To Kill a Mockingbird"
}

Odpowiedź

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Etags not supported, use '*'"
}

Wykonaj przegląd

  • Pomijanie If-Match semantyki operacji upsert (insert-or-update).
  • Służy If-Match: * do ścisłej semantyki tylko aktualizacji (404, jeśli brakuje elementu).
  • Nie używaj żadnej innej wartości. Dopasowanie rzeczywistego elementu ETag nie jest implementowane.

Uwaga / Notatka

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

  • Last updated on