Актуализиране и изтриване на редове на таблици с помощта на уеб API

Операциите за промяна на данни са основна част от уеб API. В допълнение към простите операции за актуализиране и изтриване, можете да извършвате операции върху колони на една таблица (атрибути на обекта) и да съставяте upsert заявки, които ще актуализират или вмъкват данни в зависимост от това дали съществуват.

Основна актуализация

Операциите за актуализиране използват HTTP PATCH глагола. Предайте JSON обект, съдържащ свойствата, които искате да актуализирате, на URI, който представлява записа. Връща се отговор със състояние на 204 No Content Ако актуализацията е успешна.

Заглавката If-Match: * гарантира, че няма да създадете нов запис чрез случайно извършване на upsert операция. Повече информация: Предотвратяване на създаване в upsert.

Важно

Когато актуализирате обект, включете само свойствата, които променяте, в тялото на заявката. Простото актуализиране на свойствата на обект, който сте извлекли преди това, и включването на този JSON в заявката ви ще актуализира всяко свойство, въпреки че стойността е същата. Това може да доведе до системни събития, които могат да задействат бизнес логика, която очаква стойностите да са се променили. Това може да доведе до това, че свойствата изглеждат актуализирани в данните за проверка, когато всъщност не са се променили.

Когато актуализирате statecode свойството, е важно винаги да задавате желаното statuscode. statecode и statuscode имат зависими стойности. Може да има няколко валидни statuscode стойности за дадена statecode стойност, но всяка statecode колона има една конфигурирана стойност DefaultStatus . Когато актуализирате statecode , без да statuscodeпосочвате , стойността на състоянието по подразбиране ще бъде зададена от системата. Също така, когато проверката е разрешена в таблицата и колоната statuscode , променената стойност за statuscode колоната няма да бъде записана в данните за проверка, освен ако не е посочена в операцията за актуализиране.

Бележка

Определението за атрибути включва свойство RequiredLevel . Когато това е зададено на SystemRequired, не можете да зададете тези атрибути на нулева стойност. Повече информация: Ниво на изискване за атрибут

Този пример актуализира съществуващ запис на акаунт със accountid стойност 00000000-0000-0000-00000-00000000001.

Молба:

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  
}

Отговор:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Бележка

Вижте Използване на свойства за навигация с една стойност за информация относно свързването и изключването на обекти при актуализиране.

Актуализация с върнати данни

За да извлечете данни от обект, който актуализирате, можете да съставите заявката PATCH си така, че данните от създадения запис да се връщат със състояние 200 (OK). За да получите този резултат, трябва да използвате заглавката Prefer: return=representation на заявката.

За да контролирате кои свойства да се връщат, добавете опцията $select за заявка към URL адреса към набора от обекти. Опцията за заявка се игнорира, ако се $expand използва.

Този пример актуализира обект на акаунт и връща исканите данни в отговора.

Молба:

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

Отговор:

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

Актуализиране на няколко записа в една заявка

Най-бързият начин за актуализиране на множество записи от един и същи тип в една заявка е да използвате действието UpdateMultice. Към момента на писане на тази статия действието UpdateMultiple Не всички стандартни маси поддържат това действие, но всички еластични маси го правят.

Допълнителна информация:

Актуализиране на стойност на една собственост

Когато искате да актуализирате само една стойност на свойство, използвайте PUT заявка с името на свойството, добавено към URI на обекта.

Следващият пример актуализира name свойството на съществуващ account ред със accountid стойност 00000000-0000-0000-0000-000000000001.

Молба:

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

Отговор:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Изтриване на една стойност на собственост

За да изтриете стойността на едно свойство, използвайте DELETE заявка с името на свойството, добавено към URI на обекта.

Следващият пример изтрива стойността на свойството description на обект на акаунт със accountid стойност 00000000-0000-0000-0000-00000-00000000001.

Молба:

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

Отговор:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Бележка

Това не може да се използва със свойство за навигация с една стойност за разединяване на два обекта. За алтернативен подход вижте Премахване на връзката със свойство за навигация с една стойност .

Upsert на ред на таблица

Операцията на upsert е подобна на актуализация. Той използва PATCH заявка и използва URI, за да препрати към конкретен запис. Разликата е, че ако записът не съществува, той се създава. Ако вече съществува, той се актуализира.

Upsert е ценен при синхронизиране на данни между външни системи. Външната система може да не съдържа препратка към първичния ключ на таблицата Dataverse, така че можете да конфигурирате алтернативни ключове за таблицата Dataverse, като използвате стойности от външната система, които уникално идентифицират записа и в двете системи. Повече информация: Дефиниране на алтернативни ключове за препратки към редове

Можете да видите всички алтернативни ключове, които са дефинирани за таблица, в анотациите за типа обект в документа за $metadata услуга. Повече информация: Алтернативни клавиши.

В следващия пример има таблица с име sample_thing , която има алтернативен ключ, който препраща към две колони: sample_key1 и sample_key2, които са дефинирани да съхраняват цели стойности.

Молба:

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

И за двете операции за създаване или актуализиране получавате един и същ отговор. Забележете как заглавката на OData-EntityId отговора използва ключовите стойности, а не идентификатора на първичния ключ на GUID за записа.

Отговор:

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)

Тъй като отговорът е един и същ, не можете да знаете дали операцията представлява операция Create или Update .

Ако трябва да знаете, можете да използвате заглавката Prefer: return=representation на заявката. С тази заглавка получавате 201 Created отговор при създаване на запис и 200 OK отговор при актуализиране на записа. Тази опция добавя Retrieve операция, която оказва влияние върху производителността. Ако използвате заглавката Prefer: return=representation на заявката, уверете се, че тя $select включва минималното количество данни, за предпочитане само колоната за първичен ключ. Повече информация: Актуализиране с върнати данни и Създаване с върнати данни.

Когато използвате алтернативни ключове, не трябва да включвате алтернативните стойности на ключовете в основния текст на заявката.

Когато upsert представлява Update, тези алтернативни ключови стойности се игнорират. Не можете да актуализирате алтернативни ключови стойности, докато ги използвате за идентифициране на записа.
Когато upsert представлява Create, ключовите стойности в URL адреса се задават за записа, ако не присъстват в основния текст. Така че няма нужда да ги включвате в тялото на заявката.

Повече информация: Използване на Upsert за създаване или актуализиране на запис

Бележка

Обикновено, когато създавате нов запис, ще позволите на системата да присвои стойност на GUID за първичния ключ. Това е най-добра практика, тъй като системата генерира ключове, които са оптимизирани за индекса и това подобрява производителността. Но ако трябва да създадете запис с конкретна стойност на първичен ключ, като например когато стойността на GUID на ключа се генерира от външна система, операцията upsert предоставя начин да направите това.

Предотвратяване на създаване или актуализиране с upsert

Понякога има ситуации, в които искате да извършите upsert, но искате да предотвратите една от потенциалните операции: или създаване, или актуализиране. Можете да направите това с помощта на заглавките If-Match или If-None-Match . За повече информация вижте Ограничаване на операциите на upsert.

Основно изтриване

Операцията за изтриване е лесна. Използвайте DELETE глагола с URI на обекта, който искате да изтриете. Това примерно съобщение изтрива обект на акаунт със стойност на първичния ключ accountid , равна на 000000000-0000-0000-0000-000000000001.

Молба:

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

Отговор:

Ако обектът съществува, получавате нормален отговор със състояние 204, за да покажете, че изтриването е било успешно. Ако обектът не бъде намерен, ще получите отговор със статус 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Проверка за дублиращи се записи

За повече информация как да проверите за дублиращи се записи по време на операция за актуализиране вижте Откриване на дублиращи се записи по време на операция за актуализиране с помощта на уеб API.

Изтриване на няколко записа в една заявка

Най-бързият начин да изтриете няколко записа от един и същи тип в една заявка е да използвате действието DeleteMultiple . Към момента на писане на тази статия действието DeleteMultiple е функция за предварителен преглед. Стандартните маси не поддържат това действие, но всички еластични маси поддържат.

Бележка

За стандартни таблици препоръчваме да използвате действието Групово изтриване, което позволява асинхронно изтриване на записи, които съответстват на заявка. Повече информация: Групово изтриване на данни

Допълнителна информация:

Актуализиране и изтриване на документи в дялове за съхранение

Ако актуализирате или изтривате данни от еластична таблица, съхранени в дялове, не забравяйте да посочите ключа на дяла при достъп до тези данни.

Повече информация: Избор на стойност на PartitionId

Вижте също

Обратна връзка

Тази страница полезна ли беше?

Last updated on 2025-10-04

Споделяне чрез

Актуализиране и изтриване на редове на таблици с помощта на уеб API

Основна актуализация

Актуализация с върнати данни

Актуализиране на няколко записа в една заявка

Актуализиране на стойност на една собственост

Изтриване на една стойност на собственост

Upsert на ред на таблица

Предотвратяване на създаване или актуализиране с upsert

Основно изтриване

Проверка за дублиращи се записи

Изтриване на няколко записа в една заявка

Актуализиране и изтриване на документи в дялове за съхранение

Вижте също

Обратна връзка

Допълнителни ресурси