Обновление и удаление строк таблицы с помощью веб-API

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

Базовое обновление

Операции обновления используют HTTP-команду PATCH . Передайте объект JSON, содержащий свойства, которые необходимо обновить до URI, представляющего запись. Если обновление выполнено успешно, ответ возвращает состояние 204 No Content.

Заголовок If-Match: * гарантирует, что вы не создаете новую запись, случайно выполняя операцию upsert. Дополнительные сведения: Запрет создания в upsert.

Это важно

При обновлении сущности включите только свойства, которые вы изменяете в тексте запроса. Если вы обновляете сущность, включив все свойства полученной сущности, операция обновляет каждое свойство, даже если значение совпадает. Это обновление может привести к системным событиям, которые активируют бизнес-логику, которая ожидает изменения значений. Это может привести к тому, что свойства будут казаться обновлёнными в данных аудита, хотя на самом деле они не изменились.

При обновлении statecode свойства всегда задается требуемое statuscodeзначение. Значения statecode и statuscode зависят друг от друга. Для заданного statecode значения может быть несколько допустимых statuscode значений. Однако каждый statecode столбец имеет одно значение DefaultStatus , настроенное. При обновлении statecode без указания statuscodeзначения состояния система задает значение состояния по умолчанию. Кроме того, если включить аудит в таблице и statuscode столбце, измененное значение statuscode столбца не фиксируется в данных аудита, если он не указан в операции обновления.

Замечание

Определение атрибутов содержит RequiredLevel свойство. Если для этого свойства задано SystemRequiredзначение, эти атрибуты нельзя задать для значения NULL. Дополнительные сведения см. в разделе "Уровень требований атрибута".

В этом примере обновляется существующая запись учетной записи со accountid значением 00000000-0000-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 (ОК). Чтобы получить этот результат, используйте 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"  
}  
  

Обновление нескольких записей в одном запросе

Самый быстрый способ обновления нескольких записей одного типа в одном запросе — использовать действие UpdateMultiple. Не все стандартные таблицы поддерживают это действие, но все эластичные таблицы поддерживают его.

Подробнее:

• Сообщения о массовых операциях
• Пример: использование массовых операций в Web API
• Использование 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-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  
  

Замечание

Нельзя использовать этот подход с одноэлементным свойством навигации для разъединения двух сущностей. Альтернативный подход см. в разделе Отмена связи путем использования навигационного свойства с одним значением.

Добавление или обновление строки в таблице

Операция 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 , равным 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. Это действие позволяет асинхронное удаление записей, соответствующих запросу. Дополнительные сведения см. в разделе "Удаление данных в массовом режиме".

Подробнее:

• Сообщения о массовых операциях
• Пример кода эластичной таблицы
• Использование DeleteMultiple с эластичными таблицами

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

Если вы обновляете или удаляете данные эластичной таблицы, хранящиеся в разделах, укажите ключ секции при доступе к этим данным.

Дополнительные сведения: выбор значения PartitionId

См. также

Пример базовых операций веб-API (C#)
Пример базовых операций веб-API (JavaScript на стороне клиента)
Выполнение операций с помощью веб-API
Создание http-запросов и обработка ошибок
Запрос данных с помощью веб-API
Создание строки таблицы с помощью веб-API
Получение строки таблицы с помощью веб-API
Связывание и отмена связывания строк таблицы с помощью веб-API
Использование функций веб-API
Использование действий веб-API
Выполнение пакетных операций с помощью веб-API
Войти под другим пользователем с помощью веб-API
Выполнение условных операций с помощью веб-API