Format payload untuk operasi layanan Tabel

  • Artikel

Rest API layanan Table mendukung ATOM dan JSON sebagai format payload OData. Meskipun protokol ATOM didukung untuk semua versi layanan penyimpanan Azure, protokol JSON hanya didukung untuk versi 2013-08-15 dan yang lebih baru.

  • JSON adalah format payload yang direkomendasikan. JSON didukung untuk versi 2013-08-15 dan yang lebih baru. Anda harus menggunakan JSON dengan versi 2015-12-11 dan yang lebih baru.

  • ATOM didukung untuk versi yang lebih lama dari 2015-12-11.

Catatan

Operasi REST API berikut bukan API OData dan saat ini tidak mendukung JSON: Dapatkan ACL Tabel, Atur ACL Tabel, Dapatkan Properti Layanan Tabel, dan Atur Properti Layanan Tabel.

Untuk menentukan format JSON atau ATOM, tentukan nilai yang sesuai untuk Content-Type header dan Accept (dijelaskan di bawah). Perhatikan batasan berikut:

  • Header Content-Type diperlukan untuk semua permintaan yang berisi payload OData.

  • Accept Jika header tidak disediakan, maka jenis konten respons default ke application/atom+xml.

  • Menentukan $format parameter URI akan mengambil alih nilai yang ditentukan di Accept header permintaan, saat versi layanan data OData diatur ke 3.0. Lihat Mengatur Header Versi Layanan Data OData untuk detail tentang versi layanan OData.

Untuk menentukan format payload, atur Content-Type header permintaan dan Accept sesuai dengan tabel di bawah ini:

Payload Format Header Tipe Konten Terima Header Versi Layanan Data (Versi REST API) API yang Didukung
Atom application/atom+xml application/atom+xml 1.0 (Versi apa pun)

2.0 (2011-08-18 atau yang lebih baru)

3.0 (2013-08-15 atau yang lebih baru)		 QueryTables

CreateTable

Hapus Tabel

Entitas Kueri

Sisipkan Entitas

Sisipkan atau Gabungkan Entitas

Sisipkan atau Ganti Entitas

Perbarui Entitas

Entitas Penggabungan

Hapus Entitas
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Untuk detailnya, lihat bagian Format JSON di bawah ini.		 3.0 (2013-08-15 atau yang lebih baru) QueryTables

CreateTable

Hapus Tabel

Entitas Kueri

Sisipkan Entitas

Sisipkan atau Gabungkan Entitas

Sisipkan atau Ganti Entitas

Perbarui Entitas

Entitas Penggabungan

Hapus Entitas
XML application/xml application/xml T/A Dapatkan ACL Tabel

Atur ACL Tabel

Mendapatkan Properti Layanan Tabel

Mengatur Properti Layanan Tabel

Format JSON (aplikasi/json) (Versi 2013-08-15 dan yang lebih baru)

OData memperluas format JSON dengan menentukan konvensi umum untuk pasangan nama-nilai ini, mirip dengan format ATOM yang dijelaskan di atas. OData mendefinisikan sekumpulan anotasi kanonis untuk informasi kontrol seperti ID, jenis, dan tautan. Untuk detail tentang format JSON, lihat Memperkenalkan JSON.

Keuntungan utama menggunakan format JSON OData adalah bahwa bagian payload yang dapat diprediksi dapat dihilangkan untuk mengurangi ukuran payload. Untuk menyusun ulang data ini di ujung penerima, ekspresi digunakan untuk menghitung tautan yang hilang, mengetik informasi, dan mengontrol data. Untuk mengontrol apa yang dihilangkan dari payload, ada tiga tingkat yang dapat Anda tentukan sebagai bagian Accept dari header:

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Anotasi ODATA berikut didukung oleh layanan Azure Table:

  • odata.metadata: URL metadata untuk koleksi, entitas, nilai primitif, atau dokumen layanan.

  • odata.id: ID entitas, yang umumnya merupakan URL ke sumber daya.

  • odata.editlink: Tautan yang digunakan untuk mengedit/memperbarui entri, jika entitas dapat diperbarui dan odata.id tidak mewakili URL yang dapat digunakan untuk mengedit entitas.

  • odata.type: Nama jenis objek yang berisi.

  • odata.etag: ETag entitas.

  • PropertyName@odata.type, untuk properti kustom: Nama jenis properti yang ditargetkan.

  • PropertyName@odata.type, untuk properti sistem (yaitu, PrimaryKeyproperti , , RowKeydan Timestamp ): Nama jenis properti yang ditargetkan.

Informasi yang disertakan dalam setiap tingkat diringkas dalam tabel berikut:

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Ya Ya Tidak
odata.id Ya Tidak Tidak
odata.editlink Ya Tidak Tidak
odata.type Ya Tidak Tidak
odata.etag Ya Tidak Tidak
PropertyName@odata.type untuk properti kustom Ya Ya Tidak
PropertyName@odata.type untuk properti sistem Ya Tidak Tidak

Jenis Properti dalam Umpan JSON

Anotasi odata.type digunakan dalam format OData JSON untuk menentukan jenis properti terbuka. Anotasi ini ada ketika semua kondisi di bawah ini terpenuhi:

  • Tingkat kontrol JSON diatur ke atau odata=minimalmetadataodata=fullmetadata, seperti yang dibahas di bagian Format JSON .

  • Properti adalah properti kustom. Perhatikan bahwa untuk tabel Azure, hanya PartitionKeyproperti , , RowKeydan Timestamp yang merupakan properti sistem, dan informasi jenisnya dinyatakan dalam $metadata. Jenis anotasi untuk properti ini hanya ada ketika tingkat kontrol diatur ke odata=fullmetadata. Untuk informasi selengkapnya lihat Memahami Model Data Layanan Tabel.

  • Jenis properti tidak dapat ditentukan melalui heuristik deteksi jenis yang dirangkum dalam tabel di bawah ini.

Jenis Edm anotasi odata.type diperlukan Jenis JSON
Edm.Binary Ya String
Edm.Boolean Tidak Harfiah
Edm.DateTime Ya String
Edm.Double Tidak Numerik (berisi titik desimal)
Edm.Guid Ya String
Edm.Int32 Tidak Numerik (Tidak berisi titik desimal)
Edm.Int64 Ya String
Edm.String Tidak String
n/a Tidak Null

Layanan Tabel tidak mempertahankan null nilai untuk properti. Saat menulis entitas, null nilai dapat ditentukan dengan atau tanpa anotasi odata.type, dan properti apa pun dengan null nilai ditangani seolah-olah permintaan tidak berisi properti tersebut. Null Nilai properti tidak pernah dikembalikan saat mengkueri entitas.

Untuk Edm.Double, nilai NaN, Infinity dan -Infinity diwakili dalam JSON menggunakan jenis String, dan anotasi odata.type diperlukan. Layanan Tabel tidak mendukung versi negatif , NaNdan dalam format JSON tidak membedakan antara nol positif dan negatif (diperlakukan -0.0 sebagai 0.0).

Entitas JSON berikut memberikan contoh untuk masing-masing dari delapan jenis properti yang berbeda:

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

Karena PartitionKey dan RowKey merupakan properti sistem, yang berarti bahwa semua baris tabel harus menentukan properti ini, anotasi jenisnya tidak muncul di entitas. Properti ini telah ditentukan sebelumnya sebagai jenis Edm.String. Namun, properti lainnya adalah properti kustom dan oleh karena itu berisi informasi jenis yang sesuai dengan salah satu jenis primitif yang didukung dalam tabel di atas.

Contoh:

Contoh entri OData berikut menunjukkan format JSON yang dikirim sebagai permintaan untuk menyisipkan entitas ke penyimpanan Azure Table (lihat Menyisipkan Entitas untuk detail tentang operasi penyisipan):

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

Saat klien meminta sekumpulan entitas di penyimpanan Azure Table, layanan merespons dengan payload JSON (lihat Entitas Kueri untuk detail tentang operasi kueri). Umpan dapat mencakup salah satu dari tiga tingkat informasi: tidak ada metadata, metadata minimal, atau metadata penuh. Contoh berikut menunjukkan setiap jenis:

Tidak ada metadata:

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

Metadata minimal:

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

Metadata lengkap:

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

Untuk mempelajari selengkapnya tentang format OData JSON, lihat spesifikasi Format JSON OData Versi 4.0 , bersama dengan Dokumen Dukungan Standar Format JSON [MS-ODATAJSON]: Protokol OData.

Format Atom (application/atom+xml) (Versi yang lebih lama dari 2015-12-11 saja)

Atom adalah format dokumen berbasis XML yang menjelaskan kumpulan informasi terkait yang disebut sebagai umpan. Umpan terdiri dari sejumlah item, yang dikenal sebagai entri. AtomPub mendefinisikan konstruksi format tambahan untuk entri dan umpan sehingga sumber daya yang diwakilinya dapat dengan mudah dikategorikan, dikelompokkan, diedit, dan ditemukan. Namun, karena Atom tidak menentukan bagaimana data terstruktur dikodekan dengan umpan, OData mendefinisikan serangkaian konvensi untuk mewakili data terstruktur dalam umpan Atom untuk memungkinkan transfer konten terstruktur berdasarkan layanan berdasarkan OData.

Misalnya, contoh entri OData berikut menunjukkan format Atom yang dikirim melalui permintaan untuk menyisipkan entitas ke penyimpanan Azure Table menggunakan REST API (lihat Sisipkan Entitas untuk detail tentang operasi penyisipan):

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

Saat klien meminta sekumpulan entitas dalam penyimpanan Tabel, layanan merespons dengan umpan Atom, yang merupakan kumpulan entri Atom (lihat Entitas Kueri untuk detail tentang operasi kueri):

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

Jenis Properti dalam Umpan Atom

Jenis data properti ditentukan oleh Spesifikasi Protokol OData. Tidak semua jenis data yang ditentukan oleh spesifikasi didukung oleh layanan Tabel. Untuk informasi tentang jenis data yang didukung dan cara mereka memetakan ke jenis runtime bahasa umum (CLR), lihat Memahami Model Data Layanan Tabel.

Properti dapat ditentukan dengan atau tanpa jenis data eksplisit. Jika jenis dihilangkan, properti secara otomatis dibuat sebagai jenis Edm.Stringdata .

Jika properti dibuat dengan jenis eksplisit, kueri yang mengembalikan entitas menyertakan jenis tersebut dalam umpan Atom, sehingga Anda dapat menentukan jenis properti yang ada jika perlu. Mengetahui jenis properti penting saat Anda membuat kueri yang memfilter properti tersebut. Untuk informasi selengkapnya, lihat Mengkueri Tabel dan Entitas.

Untuk Double properti, nilai NaN, , INFdan -INF digunakan dalam Atom untuk menunjukkan bukan angka, infinitas positif, dan infinitas negatif, masing-masing. Formulir Infinity dan -Infinity juga diterima. Layanan Tabel tidak mendukung versi negatif dari NaN. Dalam format Atom, ini membedakan antara positif dan nol negatif.

Lihat juga

Mengatur Header Versi Layanan Data OData
Penerapan versi untuk Azure Storage Services
Konsep Layanan Tabel