VENTAS: 1-800-867-1389

Formato de carga para las operaciones del servicio Tabla

Actualizado: agosto de 2014

La API de REST del servicio Tabla admite ATOM y JSON como formatos de carga de OData. Si bien el protocolo ATOM se admite en todas las versiones de los servicios de almacenamiento de Azure, el protocolo JSON solo se admite en las versiones posteriores a 2013-08-15.

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

Para especificar el formato ATOM o JSON, especifique los valores adecuados para los encabezados Content-Type y Accept (que se describen más adelante). 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. Vea Establecer los encabezados de versión del servicio de datos 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 (18/08/2011 o posterior)

3.0 (15/08/2013 o posterior)

QueryTables

CreateTable

Delete Table

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

Delete Table

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

Atom es un formato de documento basado en XML que describe colecciones de información relacionada denominadas fuentes. Las fuentes se componen de varios elementos, conocidos como entradas. AtomPub define construcciones adicionales de formato para las entradas y las fuentes, de forma que los recursos que representan se puedan categorizar, agrupar, editar y detectar fácilmente. Sin embargo, puesto 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 para que se puedan habilitar las transferencias de contenido estructurado mediante servicios basados en OData.

Por ejemplo, en la siguiente entrada de OData de ejemplo se muestra el formato Atom enviado a través de una solicitud para insertar una entidad en el almacenamiento Tabla de Azure mediante la API de REST (vea Insert Entity para obtener más detalles 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="http://www.w3.org/2005/Atom">
  <title />
  <updated>2008-09-18T23:46:19.3857256Z<updated/>
  <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>
      <d:Timestamp m:type="Edm.DateTime">0001-01-01T00:00:00</d:Timestamp>
    </m:properties>
  </content>
</entry>

Cuando un cliente consulta un conjunto de entidades en el almacenamiento Tabla, el servicio responde con una fuente Atom, que es una colección de entradas Atom (vea Query Entities para obtener más detalles 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="http://www.w3.org/2005/Atom">
  <title type="text">Customers</title>
  <id>https://myaccount.table.core.windows.net/Customers</id>
  <updated>2008-10-01T15:26:13Z</updated>
  <link rel="self" title="Customers" href="Customers" />
  <entry m:etag="W/&quot;0x5B168C7B6E589D2&quot;">
  <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>

La Especificación de protocolo OData define tipos de datos de propiedades. 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 el modo en que se asignan a tipos Common Language Runtime (CLR), vea Introducción al modelo de datos del servicio Tabla.

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, vea Consultar tablas y entidades.

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 acerca del formato JSON, vea 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

El servicio Tabla de Azure 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: identificador de entidad, que normalmente es 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: el nombre de tipo de la propiedad de destino.

  • PropertyName@odata.type, para propiedades del sistema (es decir, las propiedades PrimaryKey, RowKey y Timestamp): el 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

No

odata.id

No

No

odata.editlink

No

No

odata.type

No

No

odata.etag

No

No

PropertyName@odata.type para propiedades personalizadas

No

PropertyName@odata.type para propiedades del sistema

No

No

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 obtener más información, vea el tema Introducción al modelo de datos del servicio Tabla.

  • 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

Cadena

Edm.Boolean

No

Literales

Edm.DateTime

Cadena

Edm.Double

No

Numeric (contiene el separador decimal)

Edm.Guid

Cadena

Edm.Int32

No

Numeric (no contiene el separador decimal)

Edm.Int64

Cadena

Edm.String

No

Cadena

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 sonpropiedades personalizadas y, por tanto, contienen información de tipo correspondiente a uno de los tipos primitivos admitidos de la tabla anterior.

En la siguiente entrada de OData de ejemplo se muestra el formato JSON enviado como una solicitud para insertar una entidad en el almacenamiento Tabla de Azure (vea Insert Entity para obtener más detalles 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",
  "Timestamp":"0001-01-01T00:00:00"
}

Cuando un cliente consulta un conjunto de entidades en el almacenamiento Tabla de Azure, el servicio responde con una carga JSON (vea Query Entities para obtener más detalles sobre la operación de consulta). La fuente puede incluir uno de 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 OData vea la especificación Formato JSON OData versión 4.0 junto con el documento de apoyo [MS-ODATAJSON]: Normas de Formato JSON Protocolo OData.

Vea también

¿Te ha resultado útil?
(Caracteres restantes: 1500)
Gracias por sus comentarios
Mostrar:
© 2014 Microsoft