Inserir ou Substituir Entidade

Artigo
06/27/2023

A Insert Or Replace Entity operação substitui 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 Replace 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
`PUT`	`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
`PUT`	`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 Replace Entity operação envia a entidade para ser inserida como um OData conjunto de entidades. Este conjunto de entidades pode ser um JSON ou um feed Atom. 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 bem-sucedida devolve o código de estado 204 (Sem Conteúdo). 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.

PUT 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 Átomo.

PUT 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='myrowkey1')</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>

Após o pedido ser 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 Replace Entity operação não utiliza o If-Match cabeçalho. Tem de chamar esta operação com a versão 2011-08-18 ou posterior. Estes atributos distinguem esta operação da operação Atualizar Entidade .

Se utilizar a Insert Or Replace Entity operação para substituir uma entidade, quaisquer propriedades da entidade anterior serão removidas se a nova entidade não as definir. As propriedades com um null valor também são removidas.

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

PartitionKey Os valores e RowKey têm de ser valores de cadeia. PartitionKey e RowKey os valores podem ter até 1024 carateres 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 em 0000001, para garantir a ordenação adequada.

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

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

Para obter informações sobre a execução de operações de upsert em lotes, 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