Обновление и удаление строк таблицы с помощью веб-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значение, эти атрибуты нельзя задать для значения 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. На момент написания этой статьи, действие 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-0000000000001.

Просьба:

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