Formato payload para operações do serviço Tabela

  • Artigo

A API REST do serviço Tabela suporta ATOM e JSON como formatos de payload OData. Embora o protocolo ATOM seja suportado para todas as versões dos serviços de armazenamento do Azure, o protocolo JSON é suportado apenas para a versão 2013-08-15 e mais recente.

  • JSON é o formato de payload recomendado. O JSON é suportado para a versão 2013-08-15 e mais recente. Tem de utilizar jSON com a versão 2015-12-11 e posterior.

  • A ATOM é suportada para versões anteriores a 2015-12-11.

Nota

As seguintes operações da API REST não são APIs OData e atualmente não suportam 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 adequados para os Content-Type cabeçalhos e Accept (descritos abaixo). Tenha em atenção as seguintes restrições:

  • O Content-Type cabeçalho é necessário para todos os pedidos que contenham um payload OData.

  • Se o Accept cabeçalho não for fornecido, o tipo de conteúdo da resposta é predefinido para application/atom+xml.

  • Especificar o $format parâmetro URI substitui o valor especificado no cabeçalho do Accept pedido, quando a versão do serviço de dados OData está definida como 3.0. Veja Definir os Cabeçalhos de Versão do OData Data Service para obter detalhes sobre a versão do serviço OData.

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

Formato payload Cabeçalho do Tipo de Conteúdo Aceitar Cabeçalho Versão do Serviço de Dados (Versão da API REST) APIs suportadas
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

Criar Tabela

Eliminar Tabela

Entidades de Consulta

Inserir Entidades

Inserir ou Intercalar Entidade

Inserir ou Substituir Entidade

Atualizar Entidade

Entidade intercalar

Eliminar Entidade
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Para obter detalhes, veja a secção Formato JSON abaixo.		 3.0 (2013-08-15 ou posterior) QueryTables

Criar Tabela

Eliminar Tabela

Entidades de Consulta

Inserir Entidades

Inserir ou Intercalar Entidade

Inserir ou Substituir Entidade

Atualizar Entidade

Entidade intercalar

Eliminar Entidade
XML application/xml application/xml N/D Obter ACL de Tabela

Definir ACL de Tabela

Obter Propriedades do Serviço de Tabelas

Definir Propriedades do Serviço de Tabela

Formato JSON (aplicação/json) (Versões 2013-08-15 e posterior)

O OData expande o formato JSON ao definir convenções gerais para estes pares nome-valor, semelhantes ao formato ATOM descrito acima. O OData define um conjunto de anotações canónicas para informações de controlo, tais como IDs, tipo e ligações. Para obter detalhes sobre o formato JSON, consulte Introdução ao JSON.

A principal vantagem de utilizar o formato JSON do OData é que as partes previsíveis do payload podem ser omitidas para reduzir o tamanho do payload. Para reconstituir estes dados na extremidade de receção, as expressões são utilizadas para calcular ligações em falta, escrever informações e controlar dados. Para controlar o que é omitido do payload, existem três níveis que pode especificar como parte do Accept cabeçalho:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

As seguintes anotações ODATA são suportadas pelo serviço Tabela do Azure:

  • odata.metadata: o URL de metadados de uma coleção, entidade, valor primitivo ou documento de serviço.

  • odata.id: O ID da entidade, que geralmente é o URL do recurso.

  • odata.editlink: a ligação utilizada para editar/atualizar a entrada, se a entidade for atualizável e o odata.id não representar um URL que possa ser utilizado para editar a entidade.

  • odata.type: o nome do tipo do objeto que contém.

  • odata.etag: O ETag da entidade.

  • PropertyName@odata.type, para propriedades personalizadas: o nome do tipo da propriedade de destino.

  • PropertyName@odata.type, para as propriedades do sistema (ou seja, as PrimaryKeypropriedades , RowKeye Timestamp ): o nome do tipo da propriedade de destino.

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

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Yes Yes No
odata.id Yes No No
odata.editlink Yes No No
odata.type Yes No No
odata.etag Yes No No
PropertyName@odata.type para propriedades personalizadas Yes Yes No
PropertyName@odata.type para propriedades do sistema Yes No No

Tipos de Propriedade num Feed JSON

A odata.type anotação é utilizada no formato JSON OData para determinar o tipo de propriedade aberta. Esta anotação está presente quando todas as condições abaixo são satisfeitas:

  • O nível de controlo JSON está definido como odata=minimalmetadata ou odata=fullmetadata, conforme discutido na secção Formato JSON .

  • A propriedade é uma propriedade personalizada. Tenha em atenção que, para as tabelas do Azure, apenas as PartitionKeypropriedades , RowKeye Timestamp são propriedades do sistema e as respetivas informações de tipo são declaradas no $metadata. O tipo de anotação para estas propriedades só está presente quando o nível de controlo está definido como odata=fullmetadata. Para obter mais informações, veja Understanding the Table Service Data Model (Compreender o Modelo de Dados do Serviço de Tabelas).

  • Não é possível determinar o tipo da propriedade através da heurística de deteção de tipo resumida na tabela abaixo.

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

O serviço Tabela não persiste null nos valores das propriedades. Ao escrever uma entidade, um null valor pode ser especificado com ou sem uma anotação odata.type e qualquer propriedade com um null valor é processada como se o pedido não tivesse essa propriedade. Null os valores de propriedade nunca são devolvidos ao consultar entidades.

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

A seguinte entidade JSON fornece um exemplo para cada um dos oito tipos de propriedade 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"  
}

Uma vez PartitionKey que e RowKey são propriedades do sistema, o que significa que todas as linhas de tabela têm de definir estas propriedades, a anotação do tipo não aparece na entidade. Estas propriedades são predefinidas como 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 suportados na tabela acima.

Exemplos:

A seguinte entrada OData de exemplo demonstra o formato JSON enviado como um pedido para inserir uma entidade no armazenamento de Tabelas do Azure (veja 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 payload JSON (veja Entidades de Consulta para obter detalhes sobre a operação de consulta). O feed pode incluir um dos três níveis de informação: sem metadados, metadados mínimos ou metadados completos. Os exemplos seguintes 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 OData JSON, consulte a especificação OData JSON Format Version 4.0 (Formato JSON OData Versão 4.0 ), em conjunto com o Documento de Suporte de Normas de Formato JSON [MS-ODATAJSON]: Formato JSON do Protocolo OData.

Formato Atom (apenas aplicação/atom+xml) (Apenas versões anteriores a 2015-12-11)

O Atom é um formato de documento baseado em XML que descreve coleções de informações relacionadas referidas como feeds. Os feeds são compostos por vários itens, conhecidos como entradas. O AtomPub define construções de formato adicionais para entradas e feeds para que os recursos que representam possam ser facilmente categorizados, agrupados, editados e detetados. No entanto, uma vez que o Atom não define a forma como os dados estruturados são codificados com feeds, o OData define um conjunto de convenções para representar dados estruturados num feed Atom para permitir 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 através de um pedido para inserir uma entidade no armazenamento de Tabelas do Azure com a API REST (veja 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 (veja 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 num 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 são suportados pelo serviço Tabela. Para obter informações sobre os tipos de dados suportados e como mapeiam para tipos comuns de runtime de linguagem (CLR), veja Understanding the Table Service Data Model (Compreender o Modelo de Dados do Serviço de Tabelas).

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

Se uma propriedade for criada com um tipo explícito, uma consulta que devolva a entidade inclui esse tipo no feed Atom, para que possa determinar o tipo de uma propriedade existente, se necessário. Conhecer o tipo de uma propriedade é importante quando está a construir uma consulta que filtra nessa propriedade. Para obter mais informações, veja Consultar Tabelas e Entidades.

Para Double propriedades, os valores , INFe -INF são utilizados NaNem Átomo para indicar não um número, infinito positivo e infinito negativo, respetivamente. Os formulários Infinity e -Infinity também são aceites. O serviço Tabela não suporta uma versão negativa do NaN. No formato Atom, distingue entre zero positivo e negativo.

Consulte também

Definir os Cabeçalhos de Versão do Serviço de Dados OData
Versões para os Serviços de Armazenamento do Azure
Conceitos do Serviço Tabela