Inserir ou mesclar entidade

Artigo
06/27/2023

A Insert Or Merge Entity operação atualiza uma entidade existente ou insere uma nova entidade se ela não existir na tabela. Como essa operação pode inserir ou atualizar uma entidade, ela também é conhecida como uma operação upsert .

Solicitação

Você pode construir a solicitação da Insert Or Merge Entity seguinte maneira. HTTPS é recomendado. Substitua os seguintes valores pelos seus próprios valores:

myaccount pelo nome da sua conta de armazenamento
mytable pelo nome da sua tabela
myPartitionKey e myRowKey com o nome da chave de partição e da chave de linha para a entidade a ser atualizada

Método	URI da solicitação	Versão HTTP
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do Armazenamento de Tabelas do Azure como 127.0.0.1:10002, seguido pelo nome da conta de armazenamento emulada.

Método	URI da solicitação	Versão HTTP
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

O Armazenamento de Tabelas no emulador de Armazenamento difere do Armazenamento de Tabelas do Azure de várias maneiras. Para obter mais informações, consulte Diferenças entre o emulador de armazenamento e os serviços de Armazenamento do Azure.

Parâmetros do URI

Você pode especificar o parâmetro adicional a seguir no URI da solicitação.

Parâmetro	Descrição
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Tabelas.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Obrigatórios. Deve ser definido como 2011-08-18 ou posterior. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
`Content-Type`	Obrigatórios. Especifica o tipo de conteúdo da carga. Os valores possíveis são `application/atom+xml` e `application/json`. Para obter mais formação sobre tipos de conteúdo válidos, consulte Formato de conteúdo para operações de Armazenamento de Tabelas.
`Content-Length`	Obrigatórios. O tamanho do corpo da solicitação.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar o Armazenamento de Tabelas do Azure.

Corpo da solicitação

A Insert Or Merge Entity operação envia a entidade a ser inserida como um OData conjunto de entidades. Esse conjunto de entidades pode ser um conteúdo Atom ou JSON. Para obter mais informações, consulte Inserindo e atualizando entidades.

Observação

JSON é o formato de conteúdo recomendado e é o único formato com suporte para a versão 2015-12-11 e posterior.

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 204 (No Content). Para obter informações sobre códigos de status, consulte Códigos de erro e status e códigos de erro do Armazenamento de Tabelas.

Cabeçalhos de resposta

A resposta inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta	Descrição
`ETag`	O `ETag` para a entidade.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
`x-ms-version`	Indica a versão do Armazenamento de Tabelas usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
`Date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
`x-ms-client-request-id`	Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho será igual ao valor do `x-ms-client-request-id` cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1.024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, ele não estará presente na resposta.

Corpo da resposta

Nenhum.

Autorização

O proprietário da conta pode executar essa operação. Além disso, qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para executar essa operação pode fazer isso.

Exemplo de solicitação e resposta

Os exemplos a seguir mostram solicitações de exemplo que usam feeds JSON e Atom.

Observação

JSON é o formato de conteúdo recomendado e é o único formato com suporte para a versão 2015-12-11 e posterior.

JSON (versão 2013-08-15 e posterior)

Veja a seguir um exemplo de solicitação e resposta que usa JSON.

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

A solicitação é enviada com os seguintes cabeçalhos:

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

A solicitação é enviada com o seguinte corpo JSON:

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

Depois que a solicitação tiver sido enviada, a resposta a seguir será retornada:

  
HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Feed Atom (versões anteriores a 11/12/2015)

Veja a seguir uma solicitação de exemplo e uma resposta que usa Atom:

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

A solicitação é enviada com os seguintes cabeçalhos:

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

A solicitação é enviada com o seguinte corpo XML:

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

Depois que a solicitação tiver sido enviada, a resposta a seguir será retornada:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Comentários

A Insert Or Merge Entity operação usa o MERGE verbo . Você deve chamar a operação usando a versão 2011-08-18 ou posterior. Além disso, essa operação não usa o If-Match cabeçalho . Esses atributos distinguem essa operação de Update Entity, embora o corpo da solicitação seja o mesmo para as duas operações.

Se você usar a Insert Or Merge Entity operação para mesclar uma entidade, todas as propriedades da entidade anterior serão mantidas, se a solicitação não as definir ou incluí-las. As propriedades com um null valor também são mantidas.

Ao chamar a Insert or Merge Entity operação, você deve especificar valores para as propriedades do PartitionKey sistema e RowKey . Juntas, essas propriedades formam a chave primária e devem ser exclusivas dentro da tabela.

PartitionKey Os valores e RowKey devem ser valores de cadeia de caracteres. Cada valor de chave pode ter até 64 KiB de tamanho. Se você estiver usando um valor inteiro para o valor da chave, deverá converter o inteiro em uma cadeia de caracteres de largura fixa. Isso ocorre porque eles são canonicamente classificados. Por exemplo, converta o valor 1 em 0000001 para para garantir a classificação adequada.

Para digitar explicitamente uma propriedade, especifique o tipo apropriado OData definindo o m:type atributo dentro da definição de propriedade no feed Atom. Para obter mais informações sobre como digitar propriedades, consulte Inserir e atualizar entidades.

Qualquer aplicativo que possa autorizar e enviar uma solicitação HTTP MERGE pode inserir ou atualizar uma entidade.

Para obter informações sobre como executar operações upsert em lote, consulte Executando transações de grupo de entidades.

Confira também

Autorizar solicitações para o Armazenamento do Azure
Definindo os cabeçalhos de versão do serviço de dados OData
Inserindo e atualizando entidades
Status e códigos de erro
Códigos de erro do Armazenamento de Tabelas