Formato de conteúdo para operações de serviço de tabela

Artigo
06/27/2023

A API REST do serviço Tabela dá suporte a ATOM e JSON como formatos de carga OData. Embora o protocolo ATOM tenha suporte para todas as versões dos serviços de armazenamento do Azure, o protocolo JSON tem suporte apenas para a versão 2013-08-15 e mais recente.

JSON é o formato de conteúdo recomendado. Há suporte para JSON para a versão 2013-08-15 e mais recente. Você deve usar JSON com a versão 2015-12-11 e posterior.
O ATOM tem suporte para versões anteriores a 12-11 de 2015.

Observação

As seguintes operações de API REST não são APIs OData e atualmente não dão suporte a JSON: Obter ACL de Tabela, Definir ACL de Tabela, Obter Propriedades do Serviço de Tabela e Definir Propriedades do Serviço de Tabela.

Para especificar o formato JSON ou ATOM, especifique os valores apropriados para os Content-Type cabeçalhos e Accept (descritos abaixo). Observe as seguintes restrições:

O cabeçalho Content-Type é necessário para todas as solicitações que contêm uma carga OData.
Se o cabeçalho Accept não for fornecido, o tipo de conteúdo da resposta será padronizado como application/atom+xml.
Especificar o parâmetro do URI $format substitui o valor especificado no cabeçalho de solicitação Accept, quando a versão do serviço de dados OData é definida como 3.0. Consulte Configurando os cabeçalhos de versão do serviço de dados OData para obter detalhes sobre a versão do serviço OData.

Para especificar o formato de carga, defina os cabeçalhos de solicitação Content-Type e Accept de acordo com a tabela abaixo:

Formato de carga	Cabeçalho Content-Type	Aceitar o cabeçalho	Versão do serviço de dados (versão de API REST)	APIs com suporte
`Atom`	`application/atom+xml`	`application/atom+xml`	1.0 (qualquer versão) 2.0 (2011-08-18 ou posterior) 3.0 (2013-08-15 ou posterior)	QueryTables CreateTable Excluir Tabela Query Entities Inserir entidades Inserir ou mesclar entidade Inserir ou substituir entidade Update Entity Merge Entity Delete Entity
`JSON`	`application/json`	`application/json;odata=nometadata` `application/json;odata=minimalmetadata` `application/json;odata=fullmetadata` Para obter detalhes, consulte a seção Formato JSON abaixo.	3.0 (2013-08-15 ou posterior)	QueryTables CreateTable Excluir Tabela Query Entities Inserir entidades Inserir ou mesclar entidade Inserir ou substituir entidade Update Entity Merge Entity Delete Entity
`XML`	`application/xml`	`application/xml`	N/D	Obter ACL da tabela Definir ACL da tabela Obter propriedades do serviço Tabela Definir propriedades do serviço Tabela

Formato JSON (application/json) (versões 2013-08-15 e posteriores)

OData estende o formato JSON definindo as convenções gerais para esses pares de nome/valor, semelhantes ao formato ATOM descrito acima. OData define um conjunto de anotações canônicas para as informações de controle como IDs, tipo e links. Para obter detalhes sobre o formato JSON, consulte Introdução ao JSON.

A principal vantagem de usar o formato JSON de OData é que as partes previsíveis da carga podem ser omitidas para reduzir o tamanho da carga. Para reconstituir esses dados no lado do destinatário, as expressões são usadas para computar os links faltando, as informações de tipo e os dados de controle. Para controlar o que é omitido da carga, há três níveis que você pode especificar como parte do cabeçalho Accept:

application/json;odata=nometadata
application/json;odata=minimalmetadata
application/json;odata=fullmetadata

As anotações de ODATA a seguir têm suporte pelo serviço Tabela do Azure:

odata.metadata: a URL de metadados para uma coleção, entidade, valor primitivo, ou documento do serviço.
odata.id: a ID da entidade, que geralmente é a URL do recurso.
odata.editlink: o link usado para editar/atualizar a entrada, se a entidade é atualizável e o odata.id não representa uma URL que pode ser usada para editar a entidade.
odata.type: o nome do tipo do objeto contentor.
odata.etag: a ETag da entidade.
PropertyName@odata.type, para propriedades personalizadas: o nome do tipo da propriedade de destino.
PropertyName@odata.type, para propriedades do sistema (ou seja,, as propriedades PrimaryKey, RowKey e Timestamp): o nome do tipo da propriedade de destino.

As informações incluídas em cada nível estão resumidas na seguinte tabela:

`Annotations`	`odata=fullmetadata`	`odata=minimalmetadata`	`odata=nometadata`
`odata.metadata`	Sim	Yes	Não
`odata.id`	Sim	Não	Não
`odata.editlink`	Yes	Não	Não
`odata.type`	Sim	Não	Não
`odata.etag`	Sim	Não	Não
`PropertyName@odata.type` para propriedades personalizadas	Sim	Yes	Não
`PropertyName@odata.type` para propriedades de sistema	Sim	Não	Não

Tipos de propriedade em um feed JSON

A anotação odata.type é usada no formato OData JSON para determinar o tipo de uma propriedade aberta. Essa anotação estará presente quando todas as condições abaixo forem atendidas:

O nível de controle JSON é definido como odata=minimalmetadata ou odata=fullmetadata, conforme descrito na seção Formato JSON.
A propriedade é personalizada. Observe que, para tabelas do Azure, somente as propriedades PartitionKey, RowKey e Timestamp são propriedades de sistema, e suas informações de tipo são declarada em $metadata. A anotação de tipo para essas propriedades deverão estar presentes somente quando o nível de controle for definido como odata=fullmetadata. Para obter mais informações, consulte Noções básicas sobre o modelo de dados de serviço de tabela.
O tipo da propriedade não pode ser determinado pela heurística de detecção de tipo resumida na tabela abaixo.

Tipo de Edm	anotação de odata.type necessária	Tipo JSON
`Edm.Binary`	Sim	String
`Edm.Boolean`	Não	Literais
`Edm.DateTime`	Sim	String
`Edm.Double`	Não	Numérico (contém o ponto decimal)
`Edm.Guid`	Sim	String
`Edm.Int32`	Não	Numérico (não contém o ponto decimal)
`Edm.Int64`	Sim	String
`Edm.String`	Não	String
n/a	Não	Null

O serviço Tabela não persiste null valores para propriedades. Ao gravar uma entidade, um null valor pode ser especificado com ou sem uma anotação odata.type e qualquer propriedade com um null valor é tratada como se a solicitação não contivesse essa propriedade. Null os valores de propriedade nunca são retornados ao consultar entidades.

Para Edm.Double, os valores e Infinity-Infinity são representados NaNem JSON usando o tipo Stringe uma anotação odata.type é necessária. O serviço Tabela não dá suporte a uma versão negativa do NaNe, no formato JSON, ele não distingue entre zero positivo e negativo (trata -0.0 como 0.0).

A entidade JSON a seguir fornece um exemplo para cada um dos oito tipos de propriedades diferentes:

{  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey",  
  "DateTimeProperty@odata.type":"Edm.DateTime",  
  "DateTimeProperty":"2013-08-02T17:37:43.9004348Z",  
  "BoolProperty":false,  
  "BinaryProperty@odata.type":"Edm.Binary",  
  "BinaryProperty":"AQIDBA==",  
  "DoubleProperty":1234.1234,  
  "GuidProperty@odata.type":"Edm.Guid",  
  "GuidProperty":"4185404a-5818-48c3-b9be-f217df0dba6f",  
  "Int32Property":1234,  
  "Int64Property@odata.type":"Edm.Int64",  
  "Int64Property":"123456789012",  
  "StringProperty":"test"  
}

Como PartitionKey e RowKey são propriedades do sistema, o que significa que todas as linhas da tabela devem definir essas propriedades, sua anotação do tipo não aparece na entidade. Essas propriedades são predefinidas como o tipo Edm.String. No entanto, as outras propriedades são propriedades personalizadas e, portanto, contêm informações de tipo correspondentes a um dos tipos primitivos com suporte na tabela acima.

Exemplos:

O exemplo de entrada OData a seguir demonstra o formato JSON enviado como uma solicitação para inserir uma entidade no armazenamento de Tabelas do Azure (consulte Inserir Entidade para obter detalhes sobre a operação de inserção):

{  
  "Address":"Mountain View",  
  "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":true,  
  "NumOfOrders@odata.type":"Edm.Int64",  
  "NumOfOrders":"255",  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey1",  
}

Quando um cliente consulta um conjunto de entidades no armazenamento de Tabelas do Azure, o serviço responde com um conteúdo JSON (consulte Entidades de consulta para obter detalhes sobre a operação de consulta). O feed pode incluir um dos três níveis de informações: sem metadados, metadados mínimos ou metadados completos. Os exemplos a seguir demonstram cada tipo:

Sem metadados:

{  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Metadados mínimos:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers,  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Metadados completos:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
  "value":[  
    {  
      "odata.type":"myaccount.Customers",  
      "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')",  
      "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
      "odata.editLink":"Customers(PartitionKey='Customer03',RowKey='Name')",  
      "PartitionKey":"Customer03,  
      "RowKey":"Name",  
      "Timestamp@odata.type":"Edm.DateTime",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Para saber mais sobre o formato JSON do OData, confira a especificação OData JSON Format Versão 4.0 , em conjunto com o documento de suporte [MS-ODATAJSON]: Padrões de formato JSON do protocolo OData.

Formato Atom (aplicativo/atom+xml) (somente versões anteriores a 12-11 de 2015)

Atom é um formato de documento baseado em XML que descreve coleções de informações relacionadas conhecidas como feeds. Os feeds são compostos de um número de itens, conhecidos como entradas. AtomPub define constructos de formato adicionais para entradas e feeds para que os recursos que eles representam possam ser facilmente categorizados, agrupados, editados e descobertos. No entanto, como o Atom não define como os dados estruturados são codificados com feeds, o OData define um conjunto de convenções para representar dados estruturados em um feed Atom para habilitar transferências de conteúdo estruturado por serviços baseados em OData.

Por exemplo, a seguinte entrada OData de exemplo demonstra o formato Atom enviado por meio de uma solicitação para inserir uma entidade no armazenamento de Tabelas do Azure usando a API REST (consulte Inserir Entidade para obter detalhes sobre a operação de inserção):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<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 />  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</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>

Quando um cliente consulta um conjunto de entidades no armazenamento de Tabelas, o serviço responde com um feed Atom, que é uma coleção de entradas Atom (consulte Entidades de consulta para obter detalhes sobre a operação de consulta):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<feed xml:base="https://myaccount.table.core.windows.net/" 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 type="text">Customers</title>  
  <id>https://myaccount.table.core.windows.net/Customers</id>  
  <link rel="self" title="Customers" href="Customers" />  
  <entry m:etag="W/"0x5B168C7B6E589D2"">  
  <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')</id>  
    <title type="text"></title>  
    <updated>2008-10-01T15:26:13Z</updated>  
    <author>  
      <name />  
    </author>  
    <link rel="edit" title="Customers" href="Customers (PartitionKey='Customer03',RowKey='Name')" />  
    <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
    <content type="application/xml">  
      <m:properties>  
        <d:PartitionKey>Customer03</d:PartitionKey>  
        <d:RowKey>Name</d:RowKey>        <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
      </m:properties>  
    </content>  
  </entry>  
</feed>

Tipos de propriedade em um feed Atom

Os tipos de dados de propriedade são definidos pela Especificação do Protocolo OData. Nem todos os tipos de dados definidos pela especificação têm suporte no serviço Tabela. Para obter informações sobre os tipos de dados com suporte e como eles são mapeados para tipos CLR (Common Language Runtime), consulte Noções básicas sobre o modelo de dados do Serviço de Tabela.

Uma propriedade pode ser especificada com ou sem um tipo de dados explícito. Se o tipo for omitido, a propriedade será criada automaticamente como tipo Edm.Stringde dados .

Se uma propriedade for criada com um tipo explícito, uma consulta que retornar a entidade incluirá esse tipo no feed Atom, para que você possa determinar o tipo de uma propriedade existente, se necessário. Saber o tipo da propriedade é importante quando você está construindo uma consulta que é filtrada com base nessa propriedade. Para obter mais informações, consulte Consultando tabelas e entidades.

Para Double propriedades, os valores , INFe -INF são usados NaNno Atom para indicar não um número, infinito positivo e infinito negativo, respectivamente. Os formulários Infinity e -Infinity também são aceitos. O serviço Tabela não dá suporte a uma versão negativa do NaN. No formato Atom, ele distingue entre zero positivo e negativo.

Consulte Também

Definindo os cabeçalhos da versão do serviço de dados OData
Controle de versão para os serviços do Armazenamento do Azure
Conceitos do Serviço da Tabela

Compartilhar via