Поділитися через

Оновіть і видаляйте рядки таблиці за допомогою Web API

Операції, що змінюють дані, є основною частиною веб-API. Окрім простих операцій оновлення та видалення, ви можете виконувати операції з окремими стовпцями таблиці (атрибути сутності) та створювати upsert-запити, які оновлюють або вставляють дані залежно від наявності даних.

Базове оновлення

Для операцій оновлення використовується дієслово HTTP PATCH . Передайте об'єкт JSON, що містить властивості, які потрібно оновити, до URI, який представляє запис. Якщо оновлення успішне, відповідь повертає статус 204 No Content.

Заголовок If-Match: * гарантує, що ви не створите новий запис випадково виконавши операцію перевороту. Для отримання додаткової інформації див. Prevent create in upsert.

Важливо

При оновленні сутності включайте в тіло запиту тільки ті властивості, які ви змінюєте. Якщо ви оновлюєте сутність, включивши всі властивості сутності, які ви раніше отримали, операція оновлює кожну властивість, навіть якщо значення однакове. Це оновлення може спричинити системні події, які запускають бізнес-логіку, що очікує, що значення змінилися. Це може призвести до того, що властивості виглядають оновленими в аудиторських даних, хоча насправді вони не змінювалися.

Коли оновлюєте statecode властивість, завжди встановлюйте бажану statuscode. Значення statecode і statuscode залежать одне від одного. Для заданого statecode значення може існувати кілька допустимих statuscode значень. Однак кожен statecode стовпець має налаштоване одне значення DefaultStatus . Коли ви оновлюєте statecode без вказівки statuscode, система встановлює значення статусу за замовчуванням. Також, якщо ви увімкнули аудит у таблиці та стовпці statuscode , змінене значення statuscode стовпця не відображається в даних аудиту, якщо ви не вкажете це в операції оновлення.

Нотатка

Визначення атрибутів включає властивість RequiredLevel . Коли ця властивість встановлена на SystemRequired, ви не можете встановити ці атрибути у нульове значення. Для детальнішої інформації див. Рівень вимоги атрибутів.

Цей приклад оновлює наявний запис облікового запису зі accountid значенням 0000000-0000-0000-000000000001.

Просити:

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

Оновлення кількох записів за один запит

Найшвидший спосіб оновити кілька записів одного типу в одному запиті – це використовувати дію UpdateMulti. Не всі стандартні таблиці підтримують цю дію, але всі еластичні столи підтримують.

Додаткові відомості:

Оновлення окремого значення властивості

Щоб оновити значення однієї властивості, використовуйте 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 властивості облікової сутності з значенням accountid00000000-0000-0000-0000-000000000001.

Просити:

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

Нотатка

Цей підхід не можна використовувати з однозначною навігаційною властивістю, щоб відокремити дві сутності. Для альтернативного підходу див. розділ «Відсторонення з використанням властивості навігації з одним значенням».

Перевернути рядок таблиці

Операція апсерта схожа на оновлення. Він використовує 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)

Оскільки відповідь однакова, ви не можете знати, чи операція представляла операцію або CreateUpdate її.

Якщо вам потрібно дізнатися, ви можете використовувати Prefer: return=representation заголовок запиту. Використовуючи цей заголовок, ви отримуєте 201 Created відповідь при створенні запису і 200 OK відповідь при його оновленні. Цей параметр додає Retrieve операцію, яка впливає на продуктивність. Якщо ви використовуєте Prefer: return=representation заголовок запиту, переконайтеся, що він $select включає мінімальну кількість даних, бажано лише стовпець первинного ключа. Додаткові відомості: Оновлення з поверненими даними та Створення з поверненими даними.

При використанні альтернативних ключів не включайте значення альтернативних ключів у тіло запиту.

  • Коли верхній символ представляє , Updateці альтернативні значення ключів ігноруються. Не можна оновлювати альтернативні значення ключів під час їх використання для ідентифікації запису.
  • Коли верхній символ представляє , Createзначення ключів у URL-адресі встановлюються для запису, якщо вони відсутні в тілі. Тому немає необхідності включати їх у тіло запиту.

Додаткові відомості: Використання Upsert для створення або оновлення запису

Нотатка

Зазвичай при створенні нового запису дозволяє системі призначити значення GUID для первинного ключа. Ця практика найкраща, оскільки система генерує ключі, оптимізовані для індексу, і цей вибір покращує продуктивність. Але якщо потрібно створити запис із певним значенням первинного ключа, наприклад, коли значення GUID ключа генерується зовнішньою системою, ця upsert операція дає змогу це зробити.

Запобігайте, створюйте або оновлюйте за допомогою upsert

Іноді потрібно виконати upsert «але запобігти одній із можливих операцій»: або створити, або оновити. Ви можете запобігти цим операціям, використовуючи If-Match заголовки OR If-None-Match . Щоб дізнатися більше, перегляньте статтю Обмеження операцій з розширення.

Базове видалення

Операція видалення є простою. Використовуйте DELETE дієслово з URI сутності, яку потрібно видалити. Цей приклад повідомлення видаляє сутність облікового запису з первинним ключем accountid , що дорівнює 00000000-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 механіку, але всі еластичні — підтримують.

Нотатка

Для стандартних таблиць використовуйте дію BulkDelete. Ця дія дозволяє асинхронно видаляти записи, які відповідають запиту. Для отримання додаткової інформації дивіться розділ «Видалити дані масово».

Додаткові відомості:

Оновлення та видалення документів у розділах зберігання

Якщо ви оновлюєте або видаляєте дані еластичної таблиці, що зберігаються в розділах, вкажіть ключ розділу при доступі до цих даних.

Додаткові відомості: Вибір значення PartitionId

Дивись також

Приклад базових операцій веб-API (C#)
Приклад базових операцій веб-API (JavaScript на стороні клієнта)
Виконання операцій за допомогою Web API
Створення HTTP-запитів і обробка помилок
Запит даних за допомогою веб-API
Створення рядка таблиці за допомогою Web API
Отримання рядка таблиці за допомогою веб-API
Зв'язування та роз'єднання рядків таблиці за допомогою веб-API
Використовуйте функції веб-API
Використання дій веб-API
Виконання пакетних операцій за допомогою веб-API
Видавати себе за іншого користувача за допомогою веб-API
Виконання умовних операцій за допомогою веб-API

  • Last updated on