Udostępnij za pomocą

Aktualizowanie i usuwanie wierszy tabeli przy użyciu internetowego interfejsu API

Operacje modyfikowania danych są główną częścią internetowego interfejsu API. Oprócz prostych operacji aktualizacji i usuwania można wykonywać operacje na kolumnach pojedynczej tabeli (atrybutach jednostki) i tworzyć żądania upsert , które będą aktualizować lub wstawiać dane w zależności od tego, czy istnieje.

Podstawowa aktualizacja

Operacje aktualizacji używają czasownika HTTP PATCH . Przekaż obiekt JSON do adresu URI, który reprezentuje rekord, zawierający właściwości, które chcesz zaktualizować. Odpowiedź ze stanem 204 No Content jest zwracana, jeśli aktualizacja zakończyła się pomyślnie.

Nagłówek If-Match: * gwarantuje, że nie utworzysz nowego rekordu, przypadkowo wykonując operację upsert. Więcej informacji: Zapobieganie tworzeniu w operacji upsert.

Ważne

Podczas aktualizowania jednostki uwzględnij tylko właściwości, które zmieniasz w treści żądania. Wystarczy zaktualizować właściwości jednostki, którą wcześniej pobrano, a w żądaniu dołączyć odpowiedni kod JSON, aby zaktualizować każdą właściwość, nawet jeśli wartość pozostaje taka sama. Może to spowodować zdarzenia systemowe, które mogą wyzwalać logikę biznesową, która oczekuje zmiany wartości. Może to spowodować, że właściwości zostaną zaktualizowane w danych inspekcji, gdy w rzeczywistości nie zostały one rzeczywiście zmienione.

Podczas aktualizowania statecode właściwości ważne jest, aby zawsze ustawiać żądany element statuscode. statecode i statuscode mają wartości zależne. Dla danej statuscode wartości może istnieć wiele prawidłowych statecode wartości, ale każda statecode kolumna ma skonfigurowaną pojedynczą wartość DefaultStatus. Podczas aktualizacji statecode bez określania parametru statuscodewartość stanu domyślnego zostanie ustawiona przez system. Ponadto w przypadku włączenia inspekcji w tabeli i statuscode kolumnie zmieniona wartość statuscode kolumny nie zostanie przechwycona w danych inspekcji, chyba że zostanie określona w operacji aktualizacji.

Uwaga / Notatka

Definicja atrybutów zawiera RequiredLevel właściwość . Jeśli to ustawienie to SystemRequired, nie można ustawić tych atrybutów na wartość null. Więcej informacji: Poziom wymagania atrybutu

W tym przykładzie zaktualizowano istniejący rekord konta o accountid wartości 000000000-0000-0000-0000-00000000001.

Prosić:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

Odpowiedź:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Uwaga / Notatka

Zobacz Using single-valued navigation properties (Używanie właściwości nawigacji jednowartościowej ), aby uzyskać informacje na temat kojarzenia i rozłączania jednostek podczas aktualizacji.

Aktualizacja przy użyciu zwróconych danych

Aby pobrać dane z aktualizowanej jednostki, możesz utworzyć PATCH żądanie, aby dane z utworzonego rekordu zostały zwrócone ze stanem 200 (OK). Aby uzyskać ten wynik, należy użyć nagłówka Prefer: return=representation żądania.

Aby kontrolować, które właściwości są zwracane, dołącz $select opcję zapytania do adresu URL zestawu jednostek. Opcja $expand zapytania jest ignorowana, jeśli jest używana.

Ten przykład aktualizuje jednostkę konta i zwraca żądane dane w odpowiedzi.

Prosić:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Odpowiedź:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Aktualizowanie wielu rekordów w jednym żądaniu

Najszybszym sposobem aktualizowania wielu rekordów tego samego typu w jednym żądaniu jest użycie akcji UpdateMultiple. W momencie pisania tego tekstu akcja UpdateMultiple. Nie wszystkie standardowe tabele obsługują tę akcję, ale wszystkie tabele elastyczne działają.

Więcej informacji:

Aktualizowanie pojedynczej wartości właściwości

Jeśli chcesz zaktualizować tylko jedną wartość właściwości, użyj żądania PUT z nazwą właściwości dołączoną do identyfikatora URI jednostki.

Poniższy przykład aktualizuje name właściwość istniejącego account wiersza o accountid wartości 0000000000-0000-0000-0000-0000-000000001.

Prosić:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Odpowiedź:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Usuwanie pojedynczej wartości właściwości

Aby usunąć wartość pojedynczej właściwości, użyj DELETE żądania o nazwie właściwości dołączonej do identyfikatora URI jednostki.

Poniższy przykład usuwa wartość description właściwości jednostki konta z wartością accountid 00000000-0000-0000-0000-000000000001.

Prosić:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Odpowiedź:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Uwaga / Notatka

Nie można jej używać z pojedynczą wartością właściwości nawigacji w celu usunięcia skojarzenia dwóch encji. Aby zapoznać się z alternatywnym podejściem, zobacz Usuń skojarzenie z właściwością nawigacji jednowartościowej (Disassociate with a single-valued navigation property).

Operacja upsert dla wiersza tabeli

Operacja upsert jest podobna do aktualizacji. Używa PATCH żądania oraz identyfikatora URI, aby odwołać się do określonego rekordu. Różnica polega na tym, że jeśli rekord nie istnieje, zostanie utworzony. Jeśli już istnieje, zostanie on zaktualizowany.

Funkcja Upsert jest cenna podczas synchronizowania danych między systemami zewnętrznymi. System zewnętrzny może nie zawierać odwołania do klucza podstawowego tabeli Dataverse, więc można skonfigurować klucze alternatywne dla tabeli Dataverse przy użyciu wartości z systemu zewnętrznego, które jednoznacznie identyfikują rekord w obu systemach. Więcej informacji: Zdefiniuj inne klawisze, aby odwoływać się do wierszy

W adnotacjach dla typu jednostki w dokumencie usługi $metadata można wyświetlić wszystkie klucze alternatywne zdefiniowane dla tabeli. Więcej informacji: Klucze alternatywne.

W poniższym przykładzie istnieje tabela o nazwie sample_thing , która zawiera klucz alternatywny, który odwołuje się do dwóch kolumn: sample_key1 i sample_key2, które są zdefiniowane do przechowywania wartości całkowitych.

Prosić:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

W przypadku operacji tworzenia lub aktualizacji otrzymasz tę samą odpowiedź. Zwróć uwagę, że nagłówek odpowiedzi OData-EntityId używa wartości klucza, a nie identyfikatora GUID klucza podstawowego dla rekordu.

Odpowiedź:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Ponieważ odpowiedź jest taka sama, nie możesz wiedzieć, czy operacja reprezentuje operację Create lub Update .

Jeśli musisz wiedzieć, możesz użyć nagłówka Prefer: return=representation żądania. W tym nagłówku otrzymasz 201 Created odpowiedź, gdy rekord zostanie utworzony, i 200 OK odpowiedź, gdy rekord zostanie zaktualizowany. Ta opcja dodaje operację Retrieve , która ma wpływ na wydajność. Jeśli używasz nagłówka Prefer: return=representation żądania, upewnij się, że $select zawiera minimalną ilość danych, najlepiej tylko kolumnę klucza podstawowego. Więcej informacji: Aktualizuj przy użyciu zwróconych danych i Utwórz przy użyciu zwróconych danych.

W przypadku używania kluczy alternatywnych nie należy uwzględniać wartości klucza alternatywnego w treści żądania.

  • Gdy element upsert reprezentuje Update, te wartości alternatywnego klucza są ignorowane. Nie można zaktualizować wartości klucza alternatywnego podczas ich używania do identyfikowania rekordu.
  • Gdy element upsert przedstawia Create, wartości klucza w adresie URL są ustawiane dla rekordu, jeśli nie są obecne w treści. Nie ma więc potrzeby dołączania ich do treści żądania.

Więcej informacji: Używanie operacji Upsert do tworzenia lub aktualizowania rekordu

Uwaga / Notatka

Zwykle podczas tworzenia nowego rekordu można zezwolić systemowi na przypisanie wartości identyfikatora GUID dla klucza podstawowego. Jest to najlepsze rozwiązanie, ponieważ system generuje klucze zoptymalizowane pod kątem indeksu i zwiększa to wydajność. Jeśli jednak musisz utworzyć rekord z określoną wartością klucza podstawowego, na przykład gdy wartość identyfikatora GUID klucza jest generowana przez system zewnętrzny, upsert operacja umożliwia wykonanie tej czynności.

Zapobieganie tworzeniu lub aktualizowaniu danych za pomocą operacji upsert

Czasami występują sytuacje, w których chcesz wykonać operację upsert, ale chcesz zapobiec jednej z potencjalnych operacji: tworzenia lub aktualizowania. Można to zrobić przy użyciu nagłówków If-Match lub If-None-Match. Aby uzyskać więcej informacji, zobacz Ograniczanie operacji upsert.

Usuwanie podstawowe

Operacja usuwania jest prosta. Użyj czasownika DELETE z identyfikatorem URI jednostki, którą chcesz usunąć. Ten przykładowy komunikat usuwa jednostkę konta z wartością klucza accountid podstawowego równą 000000000-0000-0000-0000-000000001.

Prosić:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Odpowiedź:

Jeśli jednostka istnieje, otrzymasz normalną odpowiedź ze stanem 204, aby wskazać, że usunięcie zakończyło się pomyślnie. Jeśli jednostka nie zostanie znaleziona, otrzymasz odpowiedź ze stanem 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Sprawdzanie pod kątem zduplikowanych rekordów

Aby uzyskać więcej informacji na temat sprawdzania pod kątem zduplikowanych rekordów podczas operacji aktualizacji, zobacz Wykrywanie duplikatów podczas operacji aktualizacji przy użyciu internetowego interfejsu API.

Usuwanie wielu rekordów w jednym żądaniu

Najszybszym sposobem usunięcia wielu rekordów tego samego typu w jednym żądaniu jest użycie DeleteMultiple akcji. W momencie pisania tego tekstu akcja DeleteMultiple jest funkcją w wersji zapoznawczej. Tabele standardowe nie obsługują tej akcji, ale wszystkie tabele elastyczne działają.

Uwaga / Notatka

W przypadku tabel standardowych zalecamy użycie akcji BulkDelete, która umożliwia asynchroniczne usuwanie rekordów pasujących do zapytania. Więcej informacji: Zbiorcze usuwanie danych

Więcej informacji:

Aktualizowanie i usuwanie dokumentów w partycjach przechowywania

Jeśli aktualizujesz lub usuwasz dane tabeli elastycznej przechowywane w partycjach, pamiętaj o określeniu klucza partycji podczas uzyskiwania dostępu do tych danych.

Więcej informacji: Wybieranie wartości PartitionId

Zobacz także

Przykład podstawowych operacji w interfejsie API sieci Web (C#)
Przykład podstawowych operacji internetowego interfejsu API (JavaScript po stronie klienta)
Wykonywanie operacji przy użyciu internetowego interfejsu API
Tworzenie żądań HTTP i obsługa błędów
Wykonywanie zapytań o dane przy użyciu internetowego interfejsu API
Tworzenie wiersza tabeli przy użyciu internetowego interfejsu API
Pobieranie wiersza tabeli przy użyciu internetowego interfejsu API
Kojarzenie i usuwanie skojarzenia wierszy tabeli przy użyciu internetowego interfejsu API
Korzystanie z funkcji internetowego interfejsu API
Używanie akcji internetowego interfejsu API
Wykonywanie operacji wsadowych przy użyciu interfejsu Web API
Personifikuj innego użytkownika przy użyciu internetowego interfejsu API
Wykonywanie operacji warunkowych przy użyciu internetowego interfejsu API

  • Last updated on