Inserir ou Intercalar Entidade

Artigo
06/27/2023

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

Pedir

Pode construir o pedido da Insert Or Merge Entity seguinte forma. É recomendado HTTPS. Substitua os seguintes valores pelos seus:

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

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

Serviço de armazenamento emulado

Quando fizer um pedido relativamente ao serviço de armazenamento emulado, especifique o nome de anfitrião do emulador e a porta do Armazenamento de Tabelas do Azure como 127.0.0.1:10002, seguido do nome da conta de armazenamento emulada.

Método	URI do pedido	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 formas. Para obter mais informações, veja Diferenças entre o emulador de Armazenamento e os serviços de Armazenamento do Azure.

Parâmetros do URI

Pode especificar o seguinte parâmetro adicional no URI do pedido.

Parâmetro	Description
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Table Storage operations (Definir tempos limite para operações de Armazenamento de Tabelas).

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`x-ms-version`	Obrigatório. Tem de estar definido como 2011-08-18 ou posterior. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
`Content-Type`	Obrigatório. Especifica o tipo de conteúdo do payload. Os valores possíveis são `application/atom+xml` e `application/json`. Para obter mais formação sobre tipos de conteúdo válidos, veja Formato de payload para operações de Armazenamento de Tabelas.
`Content-Length`	Obrigatório. O comprimento do corpo do pedido.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar o Armazenamento de Tabelas do Azure.

Corpo do pedido

A Insert Or Merge Entity operação envia a entidade para ser inserida como um OData conjunto de entidades. Este conjunto de entidades pode ser um payload Atom ou JSON. Para obter mais informações, veja Inserir e atualizar entidades.

Nota

JSON é o formato de payload recomendado e é o único formato suportado para a versão 2015-12-11 e posterior.

Resposta

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

Código de estado

Uma operação com êxito devolve o código de estado 204 (No Content). Para obter informações sobre códigos de estado, veja Códigos de estado e de erro e Códigos de erro do Armazenamento de Tabelas.

Cabeçalhos de resposta

A resposta inclui os seguintes cabeçalhos. 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 o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
`x-ms-version`	Indica a versão do Armazenamento de Tabelas utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos feitos na versão 2009-09-19 e posterior.
`Date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera este valor.
`x-ms-client-request-id`	Pode ser utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente no pedido, não estará presente na resposta.

Corpo da resposta

Nenhum.

Autorização

O proprietário da conta pode efetuar esta operação. Além disso, qualquer pessoa com uma assinatura de acesso partilhado que tenha permissão para efetuar esta operação pode fazê-lo.

Pedido e resposta de exemplo

Os exemplos seguintes mostram pedidos de exemplo que utilizam feeds JSON e Atom.

Nota

JSON é o formato de payload recomendado e é o único formato suportado para a versão 2015-12-11 e posterior.

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

Segue-se um pedido de exemplo e uma resposta que utiliza JSON.

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

O pedido é enviado 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

O pedido é enviado 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 de o pedido ter sido enviado, é devolvida a seguinte resposta:

  
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 2015-12-11)

Segue-se um pedido de exemplo e uma resposta que utiliza o Atom:

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

O pedido é enviado 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

O pedido é enviado 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 de o pedido ter sido enviado, é devolvida a seguinte resposta:

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

Observações

A Insert Or Merge Entity operação utiliza o MERGE verbo. Tem de chamar a operação utilizando a versão 2011-08-18 ou posterior. Além disso, esta operação não utiliza o If-Match cabeçalho. Estes atributos distinguem esta operação da Update Entity operação, embora o corpo do pedido seja o mesmo para ambas as operações.

Se utilizar a Insert Or Merge Entity operação para intercalar uma entidade, todas as propriedades da entidade anterior serão mantidas se o pedido não as definir ou incluir. As propriedades com um null valor também são mantidas.

Quando chamar a Insert or Merge Entity operação, tem de especificar valores para as propriedades do PartitionKey sistema e RowKey . Em conjunto, estas propriedades formam a chave primária e têm de ser exclusivas na tabela.

PartitionKey Os valores e RowKey têm de ser valores de cadeia. Cada valor de chave pode ter até 64 KiB de tamanho. Se estiver a utilizar um valor inteiro para o valor da chave, deve converter o número inteiro numa cadeia de largura fixa. Isto deve-se ao facto de estarem canonicamente ordenados. Por exemplo, converta o valor 1 para 0000001 para garantir uma ordenação adequada.

Para escrever explicitamente uma propriedade, especifique o tipo adequado OData ao definir o m:type atributo na definição de propriedade no feed Atom. Para obter mais informações sobre como escrever propriedades, veja Inserir e atualizar entidades.

Qualquer aplicação que possa autorizar e enviar um HTTP MERGE pedido pode inserir ou atualizar uma entidade.

Para obter informações sobre como realizar operações de upsert em lote, veja Executar transações de grupos de entidades.

Ver também

Autorizar pedidos para o Armazenamento do Azure
Definir os cabeçalhos da versão do serviço de dados OData
Inserir e atualizar entidades
Códigos de estado e de erro
Códigos de erro do Armazenamento de Tabelas