Format de charge utile pour les opérations de service de table

Article
08/05/2023

L'API REST du service Table prend en charge ATOM et JSON en tant que formats de charge utile OData. Bien que le protocole ATOM soit pris en charge pour toutes les versions des services de stockage Azure, le protocole JSON est pris en charge uniquement pour la version 2013-08-15 et les versions ultérieures.

JSON est le format de charge utile recommandé. JSON est pris en charge pour la version 2013-08-15 et les versions ultérieures. Vous devez utiliser JSON avec la version 2015-12-11 et ultérieure.
ATOM est pris en charge pour les versions antérieures à 2015-12-11.

Remarque

Les opérations d’API REST suivantes ne sont pas des API OData et ne prennent actuellement pas en charge JSON : Obtenir la liste de contrôle d’accès de table, Définir l’ACL de table, Obtenir les propriétés du service de table et Définir les propriétés du service de table.

Pour spécifier le format JSON ou ATOM, spécifiez les valeurs appropriées pour les Content-Type en-têtes et Accept (décrits ci-dessous). Notez les contraintes suivantes :

L'en-tête Content-Type est nécessaire pour toutes les demandes contenant une charge utile OData.
Si l'en-tête Accept n'est pas spécifié, le type de contenu de la réponse est par défaut application/atom+xml.
La spécification du paramètre d'URI $format remplace la valeur spécifiée dans l'en-tête de demande Accept, lorsque la version du service de données OData est définie à 3.0. Pour plus d’informations sur la version du service OData, consultez Définition des en-têtes de version du service OData.

Pour spécifier le format de charge utile, définissez les en-têtes de demande Content-Type et Accept, conformément au tableau ci-dessous :

Format de charge utile	Entête Content-Type	En-tête Accept	Version du service de données (version de l'API REST)	API prises en charge
`Atom`	`application/atom+xml`	`application/atom+xml`	1.0 (Toutes les versions) 2.0 (2011-08-18 ou version ultérieure) 3,0 (15/08/2013 ou versions ultérieures)	QueryTables CreateTable Supprimer la table Query Entities Insert Entities Insertion ou fusion d'entité Insertion ou remplacement d'entité Update Entity Merge Entity Delete Entity
`JSON`	`application/json`	`application/json;odata=nometadata` `application/json;odata=minimalmetadata` `application/json;odata=fullmetadata` Pour des informations plus détaillées, consultez la section Format JSON ci-après.	3,0 (15/08/2013 ou versions ultérieures)	QueryTables CreateTable Supprimer la table Query Entities Insert Entities Insertion ou fusion d'entité Insertion ou remplacement d'entité Update Entity Merge Entity Delete Entity
`XML`	`application/xml`	`application/xml`	N/A	Get Table ACL Set Table ACL Obtention des propriétés du service Table Définition des propriétés du service Table

Format JSON (application/json) (versions 2013-08-15 et ultérieures)

OData étend le format JSON en définissant les conventions générales de ces paires nom-valeur, similaires au format ATOM décrit ci-dessus. OData définit un ensemble d'annotations canoniques pour contrôler des informations, telles que les ID, le type et les liens. Pour plus d’informations sur le format JSON, consultez Présentation de JSON.

Le principal avantage lié à l'utilisation du format JSON d'OData est que les parties prédictibles de la charge utile peuvent être omises afin de réduire la taille de la charge utile. Pour reconstituer ces données du côté réception, des expressions sont utilisées pour calculer les chaînons manquants, les informations de type et pour contrôler les données. Pour contrôler ce qui est omis de la charge utile, il existe trois niveaux que vous pouvez spécifier dans l'en-tête Accept :

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

Les annotations ODATA suivantes sont prises en charge par le service Table Azure :

odata.metadata : URL de métadonnées pour une collection, une entité, une valeur primitive ou un document de service.
odata.id: ID d’entité, qui est généralement l’URL de la ressource.
odata.editlink : lien utilisé pour modifier/mettre à jour l'entrée, si l'entité peut être mise à jour et odata.id ne représente pas une URL qui peut être utilisée pour modifier l'entité.
odata.type : nom de type de l'objet conteneur.
odata.etag : ETag de l'entité.
PropertyName@odata.type, pour les propriétés personnalisées : nom de type de la propriété ciblée.
PropertyName@odata.typepour les propriétés système (c’est-à-dire, les PrimaryKeypropriétés , RowKeyet Timestamp ) : nom de type de la propriété ciblée.

Les informations incluses dans chaque niveau sont résumées dans le tableau suivant :

`Annotations`	`odata=fullmetadata`	`odata=minimalmetadata`	`odata=nometadata`
`odata.metadata`	Oui	Oui	Non
`odata.id`	Oui	Non	Non
`odata.editlink`	Oui	Non	Non
`odata.type`	Oui	Non	Non
`odata.etag`	Oui	Non	Non
`PropertyName@odata.type` pour les propriétés personnalisées	Oui	Oui	Non
`PropertyName@odata.type` pour les propriétés système	Oui	Non	Non

Types de propriété dans un flux JSON

L'annotation odata.type est utilisée dans le format JSON OData pour déterminer le type d'une propriété ouverte. Cette annotation est présente lorsque toutes les conditions ci-dessous sont satisfaites :

Le niveau de contrôle JSON a la valeur odata=minimalmetadata ou odata=fullmetadata, tel que l'indique la section Format JSON.
La propriété est une propriété personnalisée. Notez que pour les tables Azure, seules les propriétés PartitionKey, RowKey et Timestamp sont des propriétés système, et leurs informations de type sont déclarées dans $metadata. L'annotation de type pour ces propriétés est présente uniquement lorsque le niveau de contrôle a la valeur odata=fullmetadata. Pour plus d’informations, consultez Présentation du modèle de données du service de table.
Le type de la propriété ne peut pas être déterminé via l'heuristique de détection de type résumée dans le tableau ci-dessous.

Type Edm	annotation odata.type nécessaire	Type JSON
`Edm.Binary`	Oui	String
`Edm.Boolean`	Non	Littéraux
`Edm.DateTime`	Oui	String
`Edm.Double`	Non	Numérique (contient une virgule décimale)
`Edm.Guid`	Oui	String
`Edm.Int32`	Non	Numérique (ne contient pas de virgule décimale)
`Edm.Int64`	Oui	String
`Edm.String`	Non	String
n/a	Non	Null

Le service Table ne conserve pas les null valeurs des propriétés. Lors de l’écriture d’une entité, une null valeur peut être spécifiée avec ou sans annotation odata.type, et toute propriété avec une null valeur est gérée comme si la requête ne contenait pas cette propriété. Null les valeurs de propriété ne sont jamais retournées lors de l’interrogation d’entités.

Pour Edm.Double, les valeurs NaN, Infinity et -Infinity sont représentées dans JSON à l’aide du type String, et une annotation odata.type est requise. Le service Table ne prend pas en charge une version négative de NaNet, au format JSON, il ne fait pas la distinction entre zéro positif et négatif (il traite -0.0 comme 0.0).

Cette entité JSON fournit un exemple pour chacun des huit types de propriété différents :

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

Étant donné que PartitionKey et RowKey sont des propriétés système, ce qui signifie que toutes les lignes de table doivent définir ces propriétés, leur annotation de type n'apparaît pas dans l'entité. Ces propriétés sont prédéfinies comme type Edm.String. Toutefois, les autres propriétés sont des propriétés personnalisées et contiennent donc des informations de type correspondant à l’un des types primitifs pris en charge dans le tableau ci-dessus.

Exemples :

L’exemple d’entrée OData suivant illustre le format JSON envoyé en tant que demande d’insertion d’une entité dans le stockage Table Azure (voir Insérer une entité pour plus d’informations sur l’opération d’insertion) :

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

Lorsqu’un client interroge un ensemble d’entités dans le stockage Table Azure, le service répond avec une charge utile JSON (consultez Entités de requête pour plus d’informations sur l’opération de requête). Le flux peut inclure un des trois niveaux d'informations : aucune métadonnée, métadonnées minimales ou métadonnées complètes. Les exemples suivants illustrent chacun de ces types :

Aucune métadonnées :

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

Métadonnées minimales :

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

Métadonnées complètes :

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

Pour en savoir plus sur le format JSON OData, consultez la spécification du format JSON OData version 4.0, conjointement avec le document de prise en charge des normes de format JSON du protocole OData [MS-ODATAJSON]: OData Protocol.

Format Atom (application/atom+xml) (versions antérieures à 2015-12-11 uniquement)

Atom est un format de document XML qui décrit des collections d’informations connexes appelées flux. Les flux sont composés d'un certain nombre d'éléments, appelés entrées. AtomPub définit des constructions de format supplémentaires pour les entrées et les flux afin que les ressources qu’ils représentent puissent être facilement catégorisées, regroupées, modifiées et découvertes. Toutefois, étant donné qu’Atom ne définit pas la façon dont les données structurées sont encodées avec des flux, OData définit un ensemble de conventions pour représenter des données structurées dans un flux Atom afin d’activer les transferts de contenu structuré par les services basés sur OData.

Par exemple, l’exemple d’entrée OData suivant illustre le format Atom envoyé via une demande d’insertion d’une entité dans le stockage Table Azure à l’aide de l’API REST (voir Insérer une entité pour plus d’informations sur l’opération d’insertion) :

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

Lorsqu’un client interroge un ensemble d’entités dans le stockage Table, le service répond avec un flux Atom, qui est une collection d’entrées Atom (voir Entités de requête pour plus d’informations sur l’opération de requête) :

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

Types de propriété dans un flux Atom

Les types de données de propriété sont définis par la spécification du protocole OData. Tous les types de données définis par la spécification ne sont pas pris en charge par le service Table. Pour plus d’informations sur les types de données pris en charge et la façon dont ils sont mappés aux types CLR (Common Language Runtime), consultez Présentation du modèle de données du service de table.

Une propriété peut être spécifiée avec ou sans un type de données explicite. Si le type est omis, la propriété est automatiquement créée en tant que type de Edm.Stringdonnées .

Si une propriété est créée avec un type explicite, une requête qui renvoie l'entité inclut ce type dans le flux Atom, afin de déterminer le type d'une propriété existante si nécessaire. La connaissance d'un type de propriété est important lorsque vous construisez une requête qui utilise un filtre sur cette propriété. Pour plus d’informations, consultez Interrogation de tables et d’entités.

Pour Double les propriétés, les valeurs NaN, INFet -INF sont utilisées dans Atom pour indiquer respectivement qu’il n’y a pas de nombre, d’infini positif et d’infini négatif. Les formulaires Infinity et -Infinity sont également acceptés. Le service Table ne prend pas en charge une version négative de NaN. Au format Atom, il fait la distinction entre zéro positif et négatif.

Voir aussi

Configuration des en-têtes de version du service de données OData
Versions des services de stockage Azure
Concepts du service de Table

Partager via