Bagikan melalui

Membuat Titik Akhir OData v3 dengan Web API 2

oleh Mike Wasson

Unduh Proyek yang Selesai

Open Data Protocol (OData) adalah protokol akses data untuk web. OData menyediakan cara yang seragam untuk menyusun data, mengkueri data, dan memanipulasi himpunan data melalui operasi CRUD (membuat, membaca, memperbarui, dan menghapus). OData mendukung format AtomPub (XML) dan JSON. OData juga mendefinisikan cara untuk mengekspos metadata tentang data. Klien dapat menggunakan metadata untuk menemukan informasi jenis dan hubungan untuk himpunan data.

ASP.NET Web API memudahkan untuk membuat titik akhir OData untuk himpunan data. Anda dapat mengontrol dengan tepat operasi OData mana yang didukung titik akhir. Anda dapat menghosting beberapa titik akhir OData, bersama titik akhir non-OData. Anda memiliki kontrol penuh atas model data, logika bisnis back-end, dan lapisan data Anda.

Versi perangkat lunak yang digunakan dalam tutorial

Dukungan Web API OData ditambahkan di pembaruan ASP.NET dan Web Tools 2012.2. Namun, tutorial ini menggunakan perancah yang ditambahkan di Visual Studio 2013.

Dalam tutorial ini, Anda akan membuat titik akhir OData sederhana yang dapat dikueri klien. Anda juga akan membuat klien C# untuk titik akhir. Setelah Anda menyelesaikan tutorial ini, serangkaian tutorial berikutnya menunjukkan cara menambahkan lebih banyak fungsionalitas, termasuk hubungan entitas, tindakan, dan $expand/$select.

Membuat Proyek Visual Studio

Dalam tutorial ini, Anda akan membuat titik akhir OData yang mendukung operasi CRUD dasar. Titik akhir akan mengekspos satu sumber daya, daftar produk. Tutorial selanjutnya akan menambahkan lebih banyak fitur.

Mulai Visual Studio dan pilih Proyek Baru dari halaman Mulai. Atau, dari menu File , pilih Baru lalu Proyek.

Di panel Templat , pilih Templat terinstal dan perluas simpul Visual C#. Di bawah Visual C#, pilih Web. Pilih templat Aplikasi Web ASP.NET.

Cuplikan layar jendela proyek baru, memperlihatkan jalur ke panel templat, dan menampilkan petunjuk arah yang disorot untuk memilih opsi Aplikasi Web A S P dot NET.

Dalam dialog Proyek ASP.NET Baru , pilih templat Kosong . Di bagian "Tambahkan folder dan referensi inti untuk...", centang WEB API. Klik OK.

Cuplikan layar kotak dialog proyek A S P dot NET, memperlihatkan kotak opsi templat dan menyoroti opsi 'kosong'.

Menambahkan Model Entitas

Model adalah objek yang mewakili data dalam aplikasi Anda. Untuk tutorial ini, kita memerlukan model yang mewakili produk. Model ini sesuai dengan jenis entitas OData kami.

Di Penjelajah Solusi, klik kanan folder Model. Dari menu konteks, pilih Tambahkan lalu pilih Kelas.

Cuplikan layar kotak dialog penjelajah solusi, memperlihatkan daftar menu untuk setiap pilihan saat menyoroti masing-masing, yang mengarahkan opsi kelas.

Dalam dialog Tambahkan Item Baru , beri nama kelas "Produk".

Cuplikan layar jendela 'tambahkan proyek baru', menampilkan pengurutan default dan memperlihatkan opsi kelas, dan kata 'product dot c s' di bidang kosong di bawah ini.

Catatan

Menurut konvensi, kelas model ditempatkan di folder Model. Anda tidak perlu mengikuti konvensi ini dalam proyek Anda sendiri, tetapi kami akan menggunakannya untuk tutorial ini.

Dalam file Product.cs, tambahkan definisi kelas berikut:

public class Product
{
    public int ID { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Category { get; set; }
}

Properti ID akan menjadi kunci entitas. Klien dapat mengkueri produk berdasarkan ID. Bidang ini juga akan menjadi kunci utama dalam database back-end.

Bangun proyek sekarang. Pada langkah berikutnya, kita akan menggunakan beberapa perancah Visual Studio yang menggunakan pantulan untuk menemukan Jenis produk.

Menambahkan Pengontrol OData

Pengontrol adalah kelas yang menangani permintaan HTTP. Anda menentukan pengontrol terpisah untuk setiap entitas yang ditetapkan dalam layanan OData Anda. Dalam tutorial ini, kita akan membuat satu pengontrol.

Di Penjelajah Solusi, klik kanan folder Pengontrol. Pilih Tambahkan lalu pilih Pengontrol.

Cuplikan layar jendela penjelajah solusi, yang menyoroti opsi pengontrol yang kemudian menampilkan menu untuk menambahkan pengontrol Data O.

Dalam dialog Tambahkan Perancah , pilih "Pengontrol OData API Web 2 dengan tindakan, menggunakan Kerangka Kerja Entitas".

Cuplikan layar layar 'tambahkan perancah', memperlihatkan menu opsi pengontrol, dan menyoroti pengontrol Data Web A P I 2 O.

Dalam dialog Tambahkan Pengontrol , beri nama pengontrol "ProductsController". Pilih kotak centang "Gunakan tindakan pengontrol asinkron". Di daftar drop-down Model , pilih kelas Produk.

Cuplikan layar kotak dialog tambahkan pengontrol, menampilkan bidang untuk nama pengontrol, daftar drop-down kelas model, dan kelas konteks data.

Klik tombol Konteks data baru... . Biarkan nama default untuk jenis konteks data, dan klik Tambahkan.

Cuplikan layar jendela konteks data baru, memperlihatkan bidang untuk 'jenis konteks data baru' dan memperlihatkan nama default untuk jenis konteks data.

Klik Tambahkan dalam dialog Tambahkan Pengontrol untuk menambahkan pengontrol.

Cuplikan layar kotak dialog tambahkan pengontrol, memperlihatkan persyaratan bidang yang berbeda, dengan kotak centang untuk 'gunakan tindakan pengontrol asinkron'.

Catatan: Jika Anda mendapatkan pesan kesalahan yang mengatakan "Ada kesalahan saat mendapatkan jenisnya...", pastikan Anda membuat proyek Visual Studio setelah menambahkan kelas Produk. Perancah menggunakan pantulan untuk menemukan kelas .

Cuplikan layar Microsoft Visual Studio, menampilkan 'X' lingkaran merah diikuti dengan kata 'kesalahan' dan pesan terperinci tentang kesalahan tersebut.

Perancah menambahkan dua file kode ke proyek:

  • Products.cs mendefinisikan pengontrol API Web yang mengimplementasikan titik akhir OData.
  • ProductServiceContext.cs menyediakan metode untuk mengkueri database yang mendasar, menggunakan Kerangka Kerja Entitas.

Cuplikan layar jendela proyek, memperlihatkan menu layanan produk dan mengelilingi dua file yang baru ditambahkan di bawah pengontrol dan di bawah model.

Menambahkan EDM dan Rute

Di Penjelajah Solusi, perluas folder App_Start dan buka file bernama WebApiConfig.cs. Kelas ini menyimpan kode konfigurasi untuk Web API. Ganti kode ini dengan yang berikut:

using ProductService.Models;
using System.Web.Http;
using System.Web.Http.OData.Builder;

namespace ProductService
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
            builder.EntitySet<Product>("Products");
            config.Routes.MapODataRoute("odata", "odata", builder.GetEdmModel());
        }
    }
}

Kode ini melakukan dua hal:

  • Membuat Model Data Entitas (EDM) untuk titik akhir OData.
  • Menambahkan rute untuk titik akhir.

EDM adalah model abstrak data. EDM digunakan untuk membuat dokumen metadata dan menentukan URI untuk layanan. ODataConventionModelBuilder membuat EDM dengan menggunakan serangkaian konvensi penamaan default EDM. Pendekatan ini membutuhkan kode paling sedikit. Jika Anda ingin kontrol lebih besar atas EDM, Anda dapat menggunakan kelas ODataModelBuilder untuk membuat EDM dengan menambahkan properti, kunci, dan properti navigasi secara eksplisit.

Metode EntitySet menambahkan entitas yang diatur ke EDM:

modelBuilder.EntitySet<Product>("Products");

String "Products" mendefinisikan nama kumpulan entitas. Nama pengontrol harus cocok dengan nama kumpulan entitas. Dalam tutorial ini, set entitas diberi nama "Produk" dan pengontrol diberi nama ProductsController. Jika Anda menamai kumpulan entitas "ProductSet", Anda akan memberi nama pengontrol ProductSetController. Perhatikan bahwa titik akhir dapat memiliki beberapa set entitas. Panggil EntitySet<T> untuk setiap set entitas, lalu tentukan pengontrol yang sesuai.

Metode MapODataRoute menambahkan rute untuk titik akhir OData.

config.Routes.MapODataRoute("ODataRoute", "odata", model);

Parameter pertama adalah nama yang mudah diingat untuk rute. Klien layanan Anda tidak melihat nama ini. Parameter kedua adalah awalan URI untuk titik akhir. Mengingat kode ini, URI untuk kumpulan entitas Produk http:// hostname/odata/Products. Aplikasi Anda dapat memiliki lebih dari satu titik akhir OData. Untuk setiap titik akhir, panggil MapODataRoute dan berikan nama rute unik dan awalan URI yang unik.

Seed Database (Opsional)

Dalam langkah ini, Anda akan menggunakan Kerangka Kerja Entitas untuk menyemai database dengan beberapa data pengujian. Langkah ini bersifat opsional, tetapi memungkinkan Anda menguji titik akhir OData Anda segera.

Dari menu Alat , pilih Pengelola Paket NuGet, lalu pilih Konsol Manajer Paket. Di jendela Konsol Manajer Paket, masukkan perintah berikut:

Enable-Migrations

Ini menambahkan folder bernama Migrations dan file kode bernama Configuration.cs.

Cuplikan layar menu layanan produk penjelajah solusi, melingkari folder yang baru ditambahkan yang disebut migrasi, dan memperlihatkan file di dalamnya.

Buka file ini dan tambahkan kode berikut ke Configuration.Seed metode .

protected override void Seed(ProductService.Models.ProductServiceContext context)
{
    // New code 
    context.Products.AddOrUpdate(new Product[] {
        new Product() { ID = 1, Name = "Hat", Price = 15, Category = "Apparel" },
        new Product() { ID = 2, Name = "Socks", Price = 5, Category = "Apparel" },
        new Product() { ID = 3, Name = "Scarf", Price = 12, Category = "Apparel" },
        new Product() { ID = 4, Name = "Yo-yo", Price = 4.95M, Category = "Toys" },
        new Product() { ID = 5, Name = "Puzzle", Price = 8, Category = "Toys" },
    });
}

Di Jendela Konsol Manajer Paket, masukkan perintah berikut:

Add-Migration Initial
Update-Database

Perintah ini menghasilkan kode yang membuat database, lalu menjalankan kode tersebut.

Menjelajahi Titik Akhir OData

Di bagian ini, kita akan menggunakan Proksi Penelusuran Kesalahan Web Fiddler untuk mengirim permintaan ke titik akhir dan memeriksa pesan respons. Ini akan membantu Anda memahami kemampuan titik akhir OData.

Di Visual Studio, tekan F5 untuk memulai penelusuran kesalahan. Secara default, Visual Studio membuka browser Anda ke http://localhost:*port*, di mana port adalah nomor port yang dikonfigurasi dalam pengaturan proyek.

Anda dapat mengubah nomor port di pengaturan proyek. Di Penjelajah Solusi, klik kanan proyek dan pilih Properti. Di jendela properti, pilih Web. Masukkan nomor port di bawah Url Proyek.

Dokumen Layanan

Dokumen layanan berisi daftar kumpulan entitas untuk titik akhir OData. Untuk mendapatkan dokumen layanan, kirim permintaan GET ke URI akar layanan.

Menggunakan Fiddler, masukkan URI berikut di tab Composer : http://localhost:port/odata/, di mana port adalah nomor port.

Cuplikan layar jendela dokumen layanan, menampilkan tab yang berbeda dengan tab 'diurai' dipilih dan memperlihatkan data U R L di bidang komposer.

Klik tombol Jalankan. Fiddler mengirimkan permintaan HTTP GET ke aplikasi Anda. Anda akan melihat respons dalam daftar Sesi Web. Jika semuanya berfungsi, kode status akan menjadi 200.

Cuplikan layar daftar sesi web, memperlihatkan protokol H T T P dengan nomor hasil 200, dan alamat dan host U R L.

Klik dua kali respons di daftar Sesi Web untuk melihat detail pesan respons di tab Pemeriksa.

Cuplikan layar tab pemeriksa daftar sesi web, menampilkan respons Header Permintaan dan informasi X M L.

Pesan respons HTTP mentah akan terlihat mirip dengan yang berikut ini:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/atomsvc+xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
DataServiceVersion: 3.0
Date: Mon, 23 Sep 2013 17:51:01 GMT
Content-Length: 364

<?xml version="1.0" encoding="utf-8"?>
<service xml:base="http://localhost:60868/odata" 
    xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title type="text">Default</atom:title>
    <collection href="Products">
        <atom:title type="text">Products</atom:title>
    </collection>
    </workspace>
</service></pre>

Secara default, WEB API mengembalikan dokumen layanan dalam format AtomPub. Untuk meminta JSON, tambahkan header berikut ke permintaan HTTP:

Accept: application/json

Cuplikan layar jendela sesi web, memperlihatkan respons dari A P I di bagian Header Permintaan, dan berputar-putar di mana harus menulis permintaan j son.

Sekarang respons HTTP berisi payload JSON:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
DataServiceVersion: 3.0
Date: Mon, 23 Sep 2013 22:59:28 GMT
Content-Length: 136

{
  "odata.metadata":"http://localhost:60868/odata/$metadata","value":[
    {
      "name":"Products","url":"Products"
    }
  ]
}

Dokumen Metadata Layanan

Dokumen metadata layanan menjelaskan model data layanan, menggunakan bahasa XML yang disebut Bahasa Definisi Skema Konseptual (CSDL). Dokumen metadata menunjukkan struktur data dalam layanan, dan dapat digunakan untuk menghasilkan kode klien.

Untuk mendapatkan dokumen metadata, kirim permintaan GET ke http://localhost:port/odata/$metadata. Berikut adalah metadata untuk titik akhir yang ditunjukkan dalam tutorial ini.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
DataServiceVersion: 3.0
Date: Mon, 23 Sep 2013 23:05:52 GMT
Content-Length: 1086

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx">
  <edmx:DataServices m:DataServiceVersion="3.0" m:MaxDataServiceVersion="3.0" 
    xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
    <Schema Namespace="ProductService.Models" xmlns="http://schemas.microsoft.com/ado/2009/11/edm">
      <EntityType Name="Product">
        <Key>
          <PropertyRef Name="ID" />
        </Key>
        <Property Name="ID" Type="Edm.Int32" Nullable="false" />
        <Property Name="Name" Type="Edm.String" />
        <Property Name="Price" Type="Edm.Decimal" Nullable="false" />
        <Property Name="Category" Type="Edm.String" />
      </EntityType>
    </Schema>
    <Schema Namespace="Default" xmlns="http://schemas.microsoft.com/ado/2009/11/edm">
      <EntityContainer Name="Container" m:IsDefaultEntityContainer="true">
        <EntitySet Name="Products" EntityType="ProductService.Models.Product" />
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

Set Entitas

Untuk mendapatkan kumpulan entitas Produk, kirim permintaan GET ke http://localhost:port/odata/Products.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
DataServiceVersion: 3.0
Date: Mon, 23 Sep 2013 23:01:31 GMT
Content-Length: 459

{
  "odata.metadata":"http://localhost:60868/odata/$metadata#Products","value":[
    {
      "ID":1,"Name":"Hat","Price":"15.00","Category":"Apparel"
    },{
      "ID":2,"Name":"Socks","Price":"5.00","Category":"Apparel"
    },{
      "ID":3,"Name":"Scarf","Price":"12.00","Category":"Apparel"
    },{
      "ID":4,"Name":"Yo-yo","Price":"4.95","Category":"Toys"
    },{
      "ID":5,"Name":"Puzzle","Price":"8.00","Category":"Toys"
    }
  ]
}

Entitas

Untuk mendapatkan produk individual, kirim permintaan GET ke http://localhost:port/odata/Products(1), di mana "1" adalah ID produk.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
DataServiceVersion: 3.0
Date: Mon, 23 Sep 2013 23:04:29 GMT
Content-Length: 140

{
  "odata.metadata":"http://localhost:60868/odata/$metadata#Products/@Element","ID":1,
      "Name":"Hat","Price":"15.00","Category":"Apparel"
}

Format Serialisasi OData

OData mendukung beberapa format serialisasi:

  • Atom Pub (XML)
  • JSON "light" (diperkenalkan di OData v3)
  • JSON "verbose" (OData v2)

Secara default, WEB API menggunakan format "cahaya" AtomPubJSON.

Untuk mendapatkan format AtomPub, atur header Terima ke "application/atom+xml". Berikut adalah contoh isi respons:

<?xml version="1.0" encoding="utf-8"?>
<entry xml:base="http://localhost:60868/odata" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml">
  <id>http://localhost:60868/odata/Products(1)</id>
  <category term="ProductService.Models.Product" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <link rel="edit" href="http://localhost:60868/odata/Products(1)" />
  <link rel="self" href="http://localhost:60868/odata/Products(1)" />
  <title />
  <updated>2013-09-23T23:42:11Z</updated>
  <author>
    <name />
  </author>
  <content type="application/xml">
    <m:properties>
      <d:ID m:type="Edm.Int32">1</d:ID>
      <d:Name>Hat</d:Name>
      <d:Price m:type="Edm.Decimal">15.00</d:Price>
      <d:Category>Apparel</d:Category>
    </m:properties>
  </content>
</entry>

Anda dapat melihat satu kerugian yang jelas dari format Atom: Ini jauh lebih verbose daripada lampu JSON. Namun, jika Anda memiliki klien yang memahami AtomPub, klien mungkin lebih memilih format tersebut daripada JSON.

Berikut adalah versi ringan JSON dari entitas yang sama:

{
  "odata.metadata":"http://localhost:60868/odata/$metadata#Products/@Element",
  "ID":1,
  "Name":"Hat",
  "Price":"15.00",
  "Category":"Apparel"
}

Format lampu JSON diperkenalkan dalam versi 3 dari protokol OData. Untuk kompatibilitas mundur, klien dapat meminta format JSON "verbose" yang lebih lama. Untuk meminta JSON verbose, atur header Terima ke application/json;odata=verbose. Berikut adalah versi verbose:

{
  "d":{
    "__metadata":{
      "id":"http://localhost:18285/odata/Products(1)",
      "uri":"http://localhost:18285/odata/Products(1)",
      "type":"ProductService.Models.Product"
    },"ID":1,"Name":"Hat","Price":"15.00","Category":"Apparel"
  }
}

Format ini menyampaikan lebih banyak metadata dalam isi respons, yang dapat menambahkan overhead yang cukup besar selama seluruh sesi. Selain itu, ia menambahkan tingkat tidak langsung dengan membungkus objek dalam properti bernama "d".

Langkah berikutnya

  • Last updated on