Udostępnij przez

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

Operacje modyfikujące dane 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 aktualizują lub wstawiają 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ć. Jeśli aktualizacja zakończy się pomyślnie, odpowiedź zwróci stan 204 No Content.

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. Jeśli zaktualizujesz jednostkę, uwzględniając wszystkie właściwości jednostki, która została wcześniej pobrana, operacja aktualizuje każdą właściwość, nawet jeśli wartość jest taka sama. Ta aktualizacja może spowodować zdarzenia systemowe, które wyzwalają logikę biznesową, która oczekuje, że wartości uległy zmianie. Może to spowodować, że właściwości będą wydawały się zaktualizowane w danych audytu, nawet jeśli faktycznie się nie zmieniły.

Podczas aktualizowania właściwości statecode zawsze należy ustawić żądany element statuscode. Wartości statecode i statuscode zależą od siebie. Dla danej statecode wartości może istnieć wiele prawidłowych statuscode wartości. Jednak każda kolumna statecode ma skonfigurowaną pojedynczą wartość DefaultStatus . Podczas aktualizacji statecode bez określania statuscode, system ustawia domyślną wartość stanu. Ponadto jeśli włączysz inspekcję 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ść . Gdy ta właściwość jest ustawiona na SystemRequiredwartość , nie można ustawić tych atrybutów na wartość null. Aby uzyskać więcej informacji, zobacz Poziom wymagań 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

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

Aktualizacja przy użyciu zwróconych danych

Aby pobrać dane z jednostki, którą aktualizujesz, utwórz PATCH żądanie, aby zwracało dane ze zaktualizowanego rekordu ze stanem 200 (OK). Aby uzyskać ten wynik, użyj 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. 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

Aby zaktualizować pojedynczą wartość właściwości, użyj PUT żądania i dodaj nazwę właściwości do identyfikatora URI jednostki.

Poniższy przykład aktualizuje właściwość name istniejącego wiersza account na accountid wartość 00000000-0000-0000-0000-000000000001.

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 żądania DELETE z nazwą właściwości dołączoną do identyfikatora URI jednostki.

Poniższy przykład usuwa wartość właściwości description jednostki konta z accountid wartością 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 użyć tego podejścia z właściwością nawigacji o pojedynczej wartości, aby rozłączyć dwie jednostki. Aby zapoznać się z alternatywnym podejściem, zobacz Usuń powiązanie za pomocą właściwości nawigacyjnej o pojedynczej wartości.

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 aktualizowania 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. Korzystając z tego nagłówka, otrzymasz 201 Created odpowiedź po utworzeniu rekordu i 200 OK odpowiedzi po zaktualizowaniu rekordu. 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 uwzględniaj 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 system może przypisać wartość identyfikatora GUID dla klucza podstawowego. Jest to najlepsze rozwiązanie, ponieważ system generuje klucze zoptymalizowane pod kątem indeksu i ten wybór poprawia 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 chcesz wykonać operację upsert, ale uniknąć jednej z możliwych akcji: utworzenia lub aktualizacji. Możesz zapobiec tym operacjom, używając nagłówka 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 encję konta z kluczem głównym accountid równym wartości 00000000-0000-0000-0000-000000000001.

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

Aby usunąć wiele rekordów tego samego typu w jednym żądaniu, użyj DeleteMultiple akcji . Tabele standardowe nie obsługują tej DeleteMultiple akcji, ale wszystkie tabele elastyczne obsługują.

Uwaga / Notatka

W przypadku tabel standardowych użyj akcji BulkDelete. Ta akcja umożliwia asynchroniczne usuwanie rekordów pasujących do zapytania. Aby uzyskać więcej informacji, zobacz Zbiorcze usuwanie danych.

Więcej informacji:

Aktualizowanie i usuwanie dokumentów w partycjach przechowywania

Jeśli aktualizujesz lub usuwasz dane elastycznej tabeli przechowywane w partycjach, określ klucz 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