Formato de carga para las operaciones de Table Service

Artículo
06/27/2023

La API de REST de Table service admite ATOM y JSON como formatos de carga de OData. Aunque el protocolo ATOM es compatible con todas las versiones de los servicios de almacenamiento de Azure, el protocolo JSON solo se admite para la versión 2013-08-15 y posteriores.

JSON es el formato de carga recomendado. JSON es compatible con la versión 2013-08-15 y posteriores. Debe usar JSON con la versión 2015-12-11 y posteriores.
ATOM es compatible con versiones anteriores a 2015-12-11.

Nota

Las siguientes operaciones de LA API REST no son API de OData y actualmente no admiten JSON: Get Table ACL, Set Table ACL, Get Table Service Properties y Set Table Service Properties.

Para especificar el formato JSON o ATOM, especifique los valores adecuados para los Content-Type encabezados y Accept (descritos a continuación). Tenga en cuenta las restricciones siguientes:

El encabezado Content-Type es necesario para todas las solicitudes que contienen una carga de OData.
Si el encabezado Accept no se proporciona, el tipo de contenido de la respuesta es application/atom+xml de forma predeterminada.
Si se especifica el parámetro de URI $format, se reemplaza el valor especificado en el encabezado de solicitud Accept cuando la versión del servicio de datos OData se establece en 3.0. Consulte Establecimiento de los encabezados de versión del servicio de datos de OData para obtener más información sobre la versión del servicio OData.

Para especificar el formato de carga, establezca los encabezados de solicitud Content-Type y Accept según la tabla siguiente:

Formato de carga	Encabezado Content-Type	Encabezado Accept	Versión del servicio de datos (versión de la API de REST)	API admitidas
`Atom`	`application/atom+xml`	`application/atom+xml`	1.0 (cualquier versión) 2.0 (2011-08-18 o posterior) 3.0 (15/08/2013 o posterior)	QueryTables CreateTable Eliminar tabla Query Entities Insert Entities Insert Or Merge Entity Insert Or Replace Entity Update Entity Merge Entity Delete Entity
`JSON`	`application/json`	`application/json;odata=nometadata` `application/json;odata=minimalmetadata` `application/json;odata=fullmetadata` Para obtener información detallada, vea la sección Formato JSON más adelante.	3.0 (15/08/2013 o posterior)	QueryTables CreateTable Eliminar tabla Query Entities Insert Entities Insert Or Merge Entity Insert Or Replace Entity Update Entity Merge Entity Delete Entity
`XML`	`application/xml`	`application/xml`	N/D	Get Table ACL Set Table ACL Get Table Service Properties Set Table Service Properties

Formato JSON (application/json) (versiones 2013-08-15 y posteriores)

OData extiende el formato JSON definiendo convenciones generales para estos pares nombre-valor, de manera similar al formato ATOM descrito anteriormente. OData define un conjunto de anotaciones canónicas para controlar información como los identificadores, el tipo y los vínculos. Para obtener más información sobre el formato JSON, consulte Introducción a JSON.

La principal ventaja del uso del formato JSON de OData es que las partes predecibles de la carga se pueden omitir para reducir el tamaño de la carga. Para reconstituir estos datos en el extremo receptor, se utilizan expresiones para calcular los vínculos, la información de tipo y datos de control que faltan. Para controlar qué se ha omitido en la carga, hay tres niveles que se pueden especificar como parte del encabezado Accept:

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

Azure Table service admite las anotaciones de ODATA siguientes:

odata.metadata: dirección URL de los metadatos de una colección, entidad, valor primitivo o documento de servicio.
odata.id: el identificador de entidad, que suele ser la dirección URL del recurso.
odata.editlink: vínculo utilizado para editar o actualizar la entrada, si la entidad se puede actualizar y el odata.id no representa una dirección URL que se puede utilizar para editar la entidad.
odata.type: nombre de tipo del objeto contenedor.
odata.etag: ETag de la entidad.
PropertyName@odata.type, para propiedades personalizadas: nombre de tipo de la propiedad de destino.
PropertyName@odata.type, para propiedades del sistema (es decir, las propiedades PrimaryKey, RowKey y Timestamp): nombre de tipo de la propiedad de destino.

La información incluida en cada nivel se resume en la tabla siguiente:

`Annotations`	`odata=fullmetadata`	`odata=minimalmetadata`	`odata=nometadata`
`odata.metadata`	Sí	Sí	No
`odata.id`	Sí	No	No
`odata.editlink`	Sí	No	No
`odata.type`	Sí	No	No
`odata.etag`	Sí	No	No
`PropertyName@odata.type` para propiedades personalizadas	Sí	Sí	No
`PropertyName@odata.type` para propiedades del sistema	Sí	No	No

Tipos de propiedad de una fuente JSON

La anotación odata.type se utiliza en el formato JSON de OData para determinar el tipo de una propiedad abierta. Esta anotación está presente cuando se cumplen todas las condiciones siguientes:

El nivel de control de JSON se establece en odata=minimalmetadata o odata=fullmetadata, como se describe en la sección Formato JSON.
La propiedad es una propiedad personalizada. Tenga en cuenta que para las tablas de Azure, solo las propiedades PartitionKey, RowKey y Timestamp son propiedades del sistema, y su información de tipo se declara en $metadata. La anotación type de estas propiedades solo está presente cuando el nivel de control se establece en odata=fullmetadata. Para más información, consulte Descripción del modelo de datos de Table Service.
El tipo de la propiedad no se puede determinar mediante la heurística de detección de tipo que se resume en la tabla siguiente.

Tipo de Edm	Anotación odata.type necesaria	Tipo JSON
`Edm.Binary`	Sí	String
`Edm.Boolean`	No	Literales
`Edm.DateTime`	Sí	String
`Edm.Double`	No	Numeric (contiene el separador decimal)
`Edm.Guid`	Sí	String
`Edm.Int32`	No	Numeric (no contiene el separador decimal)
`Edm.Int64`	Sí	String
`Edm.String`	No	String
N/D	No	Null

Table service no conserva null los valores de las propiedades. Al escribir una entidad, se puede especificar un null valor con o sin una anotación odata.type y cualquier propiedad con un null valor se controla como si la solicitud no contenía esa propiedad. Null los valores de propiedad nunca se devuelven al consultar entidades.

Para Edm.Double, los valores NaNy Infinity-Infinity se representan en JSON mediante el tipo String, y se requiere una anotación odata.type. Table service no admite una versión negativa de NaNy en formato JSON no distingue entre cero positivo y negativo (trata -0.0 como 0.0).

La siguiente entidad JSON proporciona un ejemplo de cada uno de los ocho tipos de propiedad 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"  
}

Puesto que PartitionKey y RowKey son propiedades del sistema, lo que significa que todas las filas de la tabla deben definir estas propiedades, su anotación type no aparece en la entidad. Estas propiedades se predefinen como de tipo Edm.String. Sin embargo, las otras propiedades son propiedades personalizadas y, por tanto, contienen información de tipo correspondiente a uno de los tipos primitivos admitidos en la tabla anterior.

Ejemplos:

La siguiente entrada de OData de ejemplo muestra el formato JSON enviado como una solicitud para insertar una entidad en Azure Table Storage (consulte Insertar entidad para obtener más información sobre la operación de inserción):

{  
  "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",  
}

Cuando un cliente consulta un conjunto de entidades en Azure Table Storage, el servicio responde con una carga JSON (consulte Entidades de consulta para más información sobre la operación de consulta). La fuente puede incluir uno de los tres niveles de información: sin metadatos, metadatos mínimos o metadatos completos. En los ejemplos siguientes se muestra cada uno de ellos:

Sin metadatos:

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

Metadatos 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",  
    }  
}

Metadatos 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 obtener más información sobre el formato JSON de OData, consulte la especificación OData JSON Format Version 4.0 , junto con el documento [MS-ODATAJSON]: OData Protocol JSON Format Standards Support Document.

Formato Atom (solo application/atom+xml) (versiones anteriores a 2015-12-11)

Atom es un formato de documento basado en XML que describe colecciones de información relacionada a la que se hace referencia como fuentes. Las fuentes se componen de varios elementos, conocidos como entradas. AtomPub define construcciones de formato adicionales para entradas y fuentes para que los recursos que representan se puedan clasificar, agrupar, editar y detectar fácilmente. Sin embargo, dado que Atom no define cómo se codifican los datos estructurados con fuentes, OData define un conjunto de convenciones para representar datos estructurados en una fuente Atom con el fin de habilitar las transferencias de contenido estructurado por servicios basados en OData.

Por ejemplo, la siguiente entrada de OData de ejemplo muestra el formato Atom enviado a través de una solicitud para insertar una entidad en Azure Table Storage mediante la API REST (consulte Insertar entidad para obtener más información sobre la operación de inserción):

<?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>

Cuando un cliente consulta un conjunto de entidades en Table Storage, el servicio responde con una fuente Atom, que es una colección de entradas atom (consulte Entidades de consulta para obtener más información sobre la operación 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 propiedad de una fuente Atom

Los tipos de datos de propiedad se definen mediante la especificación del protocolo OData. El servicio Tabla no admite todos los tipos de datos definidos por la especificación. Para obtener información sobre los tipos de datos admitidos y cómo se asignan a los tipos de Common Language Runtime (CLR), consulte Descripción del modelo de datos de Table Service.

Las propiedades se pueden especificar con o sin un tipo de datos explícito. Si se omite el tipo, la propiedad se crea automáticamente como un tipo de datos Edm.String.

Si una propiedad se crea con un tipo explícito, cuando una consulta devuelva la entidad incluirá ese tipo en la fuente Atom para que, si fuera necesario, se pueda determinar el tipo de una propiedad existente. Conocer el tipo de una propiedad es importante cuando se crea una consulta que filtra según esa propiedad. Para obtener más información, consulte Consulta de tablas y entidades.

En Double el caso de las propiedades, los valores NaN, INFy -INF se usan en Atom para indicar no un número, infinito positivo e infinito negativo, respectivamente. Los formularios Infinity y -Infinity también se aceptan. Table service no admite una versión negativa de NaN. En formato Atom, distingue entre cero positivo y negativo.

Consulte también

Establecer los encabezados de versión del servicio de datos OData
Control de versiones para los servicios de Azure Storage
Conceptos del servicio Tabla