Formato del payload per le operazioni del servizio tabelle

Articolo
08/05/2023

L'API REST del servizio tabelle supporta Atom e JSON come formati di payload OData. Anche se il protocollo ATOM è supportato per tutte le versioni dei servizi di archiviazione di Azure, il protocollo JSON è supportato solo per la versione 2013-08-15 e successive.

JSON è il formato di payload consigliato. JSON è supportato per la versione 2013-08-15 e successive. È necessario usare JSON con la versione 2015-12-11 e successive.
ATOM è supportato per le versioni precedenti alla versione 2015-12-11.

Nota

Le operazioni DELL'API REST seguenti non sono API OData e attualmente non supportano JSON: Get Table ACL, Set Table ACL, Get Table Service Properties e Set Table Service Properties.

Per specificare il formato JSON o ATOM, specificare i valori appropriati per le Content-Type intestazioni e Accept (descritte di seguito). Notare i seguenti vincoli:

L'intestazione Content-Type è necessaria per tutte le richieste che contengono un payload OData.
Se l'intestazione Accept non è fornita, l'impostazione predefinita del tipo di contenuto della risposta è application/atom+xml.
La specifica del parametro URI $format determina la sovrascrittura del valore specificato nell'intestazione Accept della richiesta, quando la versione del servizio dati OData è impostata su 3.0. Per informazioni dettagliate sulla versione del servizio OData, vedere Impostazione delle intestazioni della versione del servizio OData .

Per specificare il formato di payload, impostare le intestazioni Content-Type e Accept della richiesta in base alla tabella che segue:

Formato di payload	Intestazione Content-Type	Intestazione Accept	Versione del servizio dati (versione API REST)	API supportate
`Atom`	`application/atom+xml`	`application/atom+xml`	1.0 (tutte le versioni) 2.0 (2011-08-18 o versione successiva) 3.0 (2013-08-15 o successive)	QueryTables CreateTable Elimina tabella 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` Per informazioni dettagliate, vedere la sezione Formato JSON più avanti.	3.0 (2013-08-15 o successive)	QueryTables CreateTable Elimina tabella 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) (versioni 2013-08-15 e successive)

OData estende il formato JSON definendo le convenzioni generali per le coppie nome/valore, in modo simile al formato Atom descritto in precedenza. OData definisce un set di annotazioni canoniche per le informazioni di controllo come gli ID, i tipi e i collegamenti. Per informazioni dettagliate sul formato JSON, vedere Introduzione a JSON.

Il vantaggio principale dell'utilizzo del formato JSON di OData è che le parti stimabili del payload possono essere omesse per ridurre le dimensioni del payload. Per ricostituire i dati sul lato ricevente, vengono utilizzate delle espressioni per calcolare i collegamenti, le informazioni sui tipi mancanti e per controllare i dati. Per controllare quali sono gli elementi del payload omessi, esistono tre livelli che è possibile specificare come parte dell'intestazione Accept:

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

Le annotazioni ODATA seguenti sono supportate dal servizio tabelle Azure:

odata.metadata: URL di metadati per una raccolta, un'entità, un valore primitivo o un documento di servizio.
odata.id: ID entità, che è in genere l'URL della risorsa.
odata.editlink: collegamento utilizzato per modificare/aggiornare la voce, se l'entità è aggiornabile e odata.id non rappresenta un URL che può essere utilizzato per modificare l'entità.
odata.type: nome del tipo dell'oggetto contenitore.
odata.etag: valore ETag dell'entità.
PropertyName@odata.type, per le proprietà personalizzate: nome del tipo della proprietà di destinazione.
PropertyName@odata.type, per le proprietà di sistema (ad esempio, le proprietà PrimaryKey, RowKey e Timestamp): nome del tipo della proprietà di destinazione.

Le informazioni incluse in ogni livello sono riepilogate nella tabella seguente:

`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` per le proprietà personalizzate	Sì	Sì	No
`PropertyName@odata.type` per le proprietà di sistema	Sì	No	No

Tipi di proprietà in un feed JSON

L'annotazione odata.type viene utilizzata nel formato JSON OData per determinare il tipo di una proprietà aperta. Questa annotazione è presente se vengono soddisfatte tutte le condizioni seguenti:

Il livello di controllo JSON è impostato su odata=minimalmetadata o odata=fullmetadata, come descritto nella sezione Formato JSON.
La proprietà è una proprietà personalizzata. Notare che per le tabelle di Azure solo le proprietà PartitionKey, RowKey e Timestamp sono proprietà di sistema e le informazioni sul tipo sono dichiarate in $metadata. L'annotazione del tipo di queste proprietà è presente solo quando il livello di controllo è impostato su odata=fullmetadata. Per altre informazioni, vedere Informazioni sul modello di dati del servizio tabelle.
Il tipo della proprietà non può essere determinato mediante l'approccio euristico di rilevamento del tipo riepilogato nella tabella che segue.

Tipo Edm	annotazione odata.type richiesta	Tipo JSON
`Edm.Binary`	Sì	string
`Edm.Boolean`	No	Valori letterali
`Edm.DateTime`	Sì	string
`Edm.Double`	No	Numerico (contiene il separatore decimale)
`Edm.Guid`	Sì	string
`Edm.Int32`	No	Numerico (non contiene il separatore decimale)
`Edm.Int64`	Sì	string
`Edm.String`	No	string
n/d	No	Null

Il servizio Tabelle non mantiene null i valori per le proprietà. Quando si scrive un'entità, un null valore può essere specificato con o senza un'annotazione odata.type e qualsiasi proprietà con un null valore viene gestita come se la richiesta non contiene tale proprietà. Null i valori delle proprietà non vengono mai restituiti quando si esegue una query sulle entità.

Per Edm.Double, i valori NaNInfinity e sono rappresentati in JSON usando il tipo Stringe -Infinity è necessaria un'annotazione odata.type. Il servizio Tabella non supporta una versione negativa di NaNe in formato JSON non distingue tra zero positivo e negativo (tratta -0.0 come 0.0).

Nell'entità JSON indicata di seguito viene fornito un esempio per ognuno degli otto tipi di proprietà:

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

Poiché PartitionKey e RowKey sono proprietà di sistema e devono quindi essere definite da tutte le righe di tabella, l'annotazione del corrispondente tipo non appare nell'entità. Queste proprietà sono predefinite come tipo Edm.String. Tuttavia, le altre proprietà sono proprietà personalizzate e quindi contengono informazioni sul tipo corrispondenti a uno dei tipi primitivi supportati nella tabella precedente.

Esempi:

La voce OData di esempio seguente illustra il formato JSON inviato come richiesta di inserire un'entità nell'archiviazione tabelle di Azure (vedere Inserisci entità per informazioni dettagliate sull'operazione di inserimento):

{  
  "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 un client esegue una query su un set di entità nell'archiviazione tabelle di Azure, il servizio risponde con un payload JSON (vedere Entità query per informazioni dettagliate sull'operazione di query). Il feed può includere uno dei tre livelli di informazioni: senza metadati, metadati minimi o metadati completi. Negli esempi seguenti viene illustrato ciascun genere.

Senza metadati:

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

Metadati minimi:

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

Metadati completi:

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

Per altre informazioni sul formato JSON OData, vedere la specifica OData JSON Format Versione 4.0 , insieme alla [MS-ODATAJSON]: Documento di supporto per standard di formato JSON del protocollo OData.

Formato Atom (solo application/atom+xml) (versioni precedenti al 2015-12-11)

Atom è un formato di documento basato su XML che descrive raccolte di informazioni correlate denominate feed. I feed sono costituiti da una serie di elementi, noti come voci. AtomPub definisce costrutti di formato aggiuntivi per voci e feed in modo che le risorse che rappresentano possano essere facilmente categorizzate, raggruppate, modificate e individuate. Tuttavia, poiché Atom non definisce il modo in cui i dati strutturati vengono codificati con feed, OData definisce un set di convenzioni per rappresentare i dati strutturati in un feed Atom per consentire il trasferimento di contenuto strutturato da servizi basati su OData.

Ad esempio, la voce OData di esempio seguente illustra il formato Atom inviato tramite una richiesta per inserire un'entità nell'archiviazione tabelle di Azure usando l'API REST (vedere Inserisci entità per informazioni dettagliate sull'operazione di inserimento):

<?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 un client esegue una query su un set di entità nell'archiviazione tabelle, il servizio risponde con un feed Atom, ovvero una raccolta di voci Atom (vedere Entità query per informazioni dettagliate sull'operazione di query):

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

Tipi di proprietà in un feed Atom

I tipi di dati delle proprietà sono definiti dalla specifica del protocollo OData. Non tutti i tipi di dati definiti nella specifica sono supportati dal servizio tabelle. Per informazioni sui tipi di dati supportati e su come vengono mappati ai tipi CLR (Common Language Runtime), vedere Informazioni sul modello di dati del servizio tabelle.

È possibile specificare una proprietà con o senza un tipo di dati esplicito. Se il tipo viene omesso, la proprietà viene creata automaticamente come tipo di Edm.Stringdati .

Se una proprietà viene creata con un tipo esplicito, una query che restituisce l'entità include il tipo nel feed Atom. In questo modo sarà possibile determinare il tipo di proprietà esistente. Conoscere il tipo della proprietà è importante per creare una query che applica filtri su quella proprietà. Per altre informazioni, vedere Esecuzione di query su tabelle ed entità.

Per Double le proprietà, i valori NaN, INFe -INF vengono usati in Atom per indicare rispettivamente un numero, un infinito positivo e un infinito negativo. I moduli Infinity e -Infinity sono accettati anche. Il servizio Tabelle non supporta una versione negativa di NaN. In formato Atom, distingue tra zero positivo e negativo.

Vedere anche

Impostazione delle intestazioni della versione di OData Data Service
Controllo delle versioni per i servizi di archiviazione di Azure
Concetti del servizio tabelle