Web API 2 ile OData v3 uç noktası oluşturma

, Mike te son

Tamamlanmış projeyi indir

Açık Veri Protokolü (OData) Web için bir veri erişim protokolüdür. OData, verileri yapılandırmak, verileri sorgulamak ve veri kümesini CRUD işlemleri (oluşturma, okuma, güncelleştirme ve silme) aracılığıyla işlemek için Tekdüzen bir yol sağlar. OData hem AtomPub (XML) hem de JSON biçimlerini destekler. OData Ayrıca veriler hakkında meta verileri açığa çıkarmak için bir yol tanımlar. İstemciler, veri kümesine ilişkin tür bilgilerini ve ilişkilerini saptamak için meta verileri kullanabilir.

ASP.NET Web API 'SI, bir veri kümesi için OData uç noktası oluşturmayı kolaylaştırır. Endpoint 'in hangi OData işlemlerini desteklediğini tam olarak denetleyebilirsiniz. OData dışı uç noktaları ile birlikte birden çok OData uç noktası barındırabilirsiniz. Veri modeliniz, arka uç iş mantığı ve veri katmanınız üzerinde tam denetim sahibi olursunuz.

Öğreticide kullanılan yazılım sürümleri

Web API OData desteği ASP.NET and Web Tools 2012,2 güncelleştirmesineeklenmiştir. Ancak, bu öğretici Visual Studio 2013 eklenen yapı iskelesi kullanır.

Bu öğreticide, istemcilerin sorgulayabilirler basit bir OData uç noktası oluşturacaksınız. Uç nokta için de bir C# istemci oluşturacaksınız. Bu Öğreticiyi tamamladıktan sonra, bir sonraki öğretici kümesinde varlık ilişkileri, Eylemler ve $expand/$select dahil daha fazla işlevsellik ekleme gösterilmektedir.

Visual Studio projesi oluşturma

Bu öğreticide, temel CRUD işlemlerini destekleyen bir OData uç noktası oluşturacaksınız. Uç nokta tek bir kaynak ve ürünlerin bir listesini ortaya çıkarır. Daha sonraki öğreticiler daha fazla özellik ekleyecek.

Visual Studio 'Yu başlatın ve başlangıç sayfasından Yeni proje ' yi seçin. Ya da Dosya menüsünde Yeni ' yi ve ardından Proje' yi seçin.

Şablonlar bölmesinde, yüklü şablonlar ' ı seçin ve görsel C# düğümünü genişletin. Görsel C# bölümünde Web' i seçin. ASP.NET Web uygulaması şablonunu seçin.

Yeni ASP.NET projesi Iletişim kutusunda boş şablonu seçin. "altında..."klasör ve çekirdek başvuruları ekleyin, Web API 'sinikontrol edin. Tamam’a tıklayın.

Varlık modeli ekleme

Model , uygulamanızdaki verileri temsil eden bir nesnedir. Bu öğreticide, bir ürünü temsil eden bir modele ihtiyacımız var. Model, OData varlık türüne karşılık gelir.

Çözüm Gezgini modeller klasörüne sağ tıklayın. Bağlam menüsünden Ekle ' yi ve ardından sınıf' ı seçin.

Yeni öğe Ekle iletişim kutusunda, "ürün"adını adlandırın.

Note

Kurala göre model sınıfları modeller klasörüne yerleştirilir. Bu kuralı kendi projelerinizde izlemeniz gerekmez, ancak bu öğreticide bunu kullanacağız.

Product.cs dosyasında aşağıdaki sınıf tanımını ekleyin:

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

ID özelliği varlık anahtarı olacak. İstemciler, ürünleri KIMLIĞE göre sorgulayabilir. Bu alan, arka uç veritabanında da birincil anahtar olmalıdır.

Projeyi şimdi oluşturun. Bir sonraki adımda, ürün türünü bulmak için yansıma kullanan bazı Visual Studio yapı iskelesi kullanacağız.

OData denetleyicisi ekleme

Denetleyici , http isteklerini işleyen bir sınıftır. OData hizmetinde her bir varlık kümesi için ayrı bir denetleyici tanımlarsınız. Bu öğreticide, tek bir denetleyici oluşturacağız.

Çözüm Gezgini, denetleyiciler klasörüne sağ tıklayın. Ekle ' yi ve ardından Denetleyici' yi seçin.

İskele Ekle iletişim kutusunda, Entity Framework"kullanarak eylemleri olan "Web API 2 OData denetleyicisi ' ni seçin.

Denetleyici Ekle iletişim kutusunda "ProductsController" adlı denetleyiciyi adlandırın. Zaman uyumsuz denetleyici eylemlerini kullan" onay kutusunu "seçin. Model açılan listesinde ürün sınıfını seçin.

Yeni veri bağlamı... düğmesine tıklayın. Veri bağlamı türü için varsayılan adı bırakın ve Ekle' ye tıklayın.

Denetleyiciyi eklemek için denetleyici Ekle iletişim kutusunda Ekle ' ye tıklayın.

Note:..."türü alınırken bir hata olduğunu "belirten bir hata iletisi alırsanız, ürün sınıfını ekledikten sonra Visual Studio projesini derlediğinizden emin olun. Scafkatlama, sınıfını bulmak için yansıma kullanır.

Scafkatlama, projeye iki kod dosyası ekler:

  • Products.cs OData uç noktasını uygulayan Web API denetleyicisini tanımlar.
  • ProductServiceContext.cs, Entity Framework kullanarak temel veritabanını sorgulamak için yöntemler sağlar.

EDM ve rota Ekle

Çözüm Gezgini ' de, uygulama_Başlat klasörünü genişletin ve WebApiConfig.cs adlı dosyayı açın. Bu sınıf, Web API 'SI için yapılandırma kodunu içerir. Bu kodu aşağıdaki kodla değiştirin:

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());
        }
    }
}

Bu kod iki şeyi yapar:

  • OData uç noktası için bir Varlık Veri Modeli (EDM) oluşturur.
  • Uç nokta için bir yol ekler.

EDM, verilerin soyut bir modelidir. EDM, meta veri belgesini oluşturmak ve hizmet için URI 'Leri tanımlamak için kullanılır. ODataConventionModelBuilder , EDM varsayılan adlandırma kuralları kümesini kullanarak bir EDM oluşturur. Bu yaklaşım için en az kod gereklidir. EDM üzerinde daha fazla denetim istiyorsanız, özellik, anahtar ve gezinti özelliklerini açıkça ekleyerek EDM oluşturmak için ODataModelBuilder sınıfını kullanabilirsiniz.

EntitySet YÖNTEMI, EDM öğesine bir varlık kümesi ekler:

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

"Products" dizesi varlık kümesinin adını tanımlar. Denetleyicinin adı, varlık kümesinin adı ile aynı olmalıdır. Bu öğreticide, varlık kümesi "Ürünler" olarak adlandırılmıştır ve denetleyicinin adı ProductsController. "ProductSet" varlık kümesini adlandırdıysanız, denetleyiciyi ProductSetControllerolarak adlandırmış olursunuz. Bir uç noktanın birden çok varlık kümesine sahip olabileceğini unutmayın. Her varlık kümesi için EntitySet<t> çağırın ve ardından karşılık gelen bir denetleyici tanımlayın.

MapODataRoute yöntemi OData uç noktası için bir yol ekler.

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

İlk parametre yol için kolay bir addır. Hizmetinizin istemcileri bu adı görmez. İkinci parametre uç noktanın URI önekidir. Bu kod verildiğinde, Products varlık kümesi URI 'SI http://hostname/OData/Products. olur. Uygulamanız birden fazla OData uç noktasına sahip olabilir. Her uç nokta için, MapODataRoute çağırın ve benzersiz bir yol adı ve BENZERSIZ bir URI öneki sağlayın.

Veritabanını çekirdek olarak (Isteğe bağlı)

Bu adımda, veritabanını bazı test verileriyle temel almak için Entity Framework kullanacaksınız. Bu adım isteğe bağlıdır, ancak OData uç noktanızı hemen test etmenizi sağlar.

Araçlar menüsünde NuGet Paket Yöneticisi' ni ve ardından Paket Yöneticisi konsolu' nu seçin. Paket Yöneticisi konsolu penceresinde, aşağıdaki komutu girin:

Enable-Migrations

Bu, geçişler adlı bir klasör ve Configuration.cs adlı bir kod dosyası ekler.

Bu dosyayı açın ve Configuration.Seed yöntemine aşağıdaki kodu ekleyin.

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" },
    });
}

Paket Yöneticisi konsolu penceresinde aşağıdaki komutları girin:

Add-Migration Initial
Update-Database

Bu komutlar veritabanını oluşturan kodu oluşturur ve ardından bu kodu yürütür.

OData uç noktasını keşfetme

Bu bölümde, uç noktalara istek göndermek ve yanıt iletilerini incelemek için Fiddler Web hata ayıklama proxy 'sini kullanacağız. Bu, bir OData uç noktasının yeteneklerini anlamanıza yardımcı olur.

Visual Studio 'da hata ayıklamayı başlatmak için F5 tuşuna basın. Varsayılan olarak, Visual Studio tarayıcınızı http://localhost:*port*için açar, burada bağlantı noktası proje ayarlarında yapılandırılan bağlantı noktası numarasıdır.

Proje ayarlarındaki bağlantı noktası numarasını değiştirebilirsiniz. Çözüm Gezgini, projeye sağ tıklayın ve Özellikler' i seçin. Özellikler penceresinde Web' i seçin. Proje URL 'sialtında bağlantı noktası numarasını girin.

Hizmet belgesi

Hizmet belgesi , OData uç noktası için varlık kümelerinin bir listesini içerir. Hizmet belgesini almak için, hizmetin kök URI 'sine bir GET isteği gönderin.

Fiddler 'ı kullanarak, Oluşturucu SEKMESINE aşağıdaki URI 'yi girin: http://localhost:port/odata/, bağlantı noktası numarası.

Yürüt düğmesine tıklayın. Fiddler uygulamanıza bir HTTP GET isteği gönderir. Yanıtı Web oturumları listesinde görmeniz gerekir. Her şey çalışıyorsa, durum kodu 200 olacaktır.

Inspector sekmesinde yanıt iletisinin ayrıntılarını görmek için Web oturumları listesinde yanıta çift tıklayın.

Ham HTTP yanıt iletisi aşağıdakine benzer görünmelidir:

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>

Varsayılan olarak, Web API 'SI, AtomPub biçimindeki hizmet belgesini döndürür. JSON istemek için, HTTP isteğine aşağıdaki üstbilgiyi ekleyin:

Accept: application/json

HTTP yanıtı şu anda bir JSON yükü içeriyor:

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

Hizmet meta verileri belgesi

Hizmet meta verileri belgesi , kavramsal şema tanım DILI (csdl) adı VERILEN bir xml dili kullanılarak hizmetin veri modelini açıklar. Meta veri belgesi, hizmette verilerin yapısını gösterir ve istemci kodu oluşturmak için kullanılabilir.

Meta veri belgesini almak için http://localhost:port/odata/$metadataiçin bir GET isteği gönderin. Bu öğreticide gösterilen uç nokta için meta veriler aşağıda verilmiştir.

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>

Varlık kümesi

Products varlık kümesini almak için http://localhost:port/odata/Productsiçin bir GET isteği gönderin.

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

Varlık

Tek bir ürün almak için, http://localhost:port/odata/Products(1)için bir GET isteği gönderin, burada "1" ürün KIMLIĞIDIR.

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

OData serileştirme biçimleri

OData birkaç serileştirme biçimini destekler:

  • Atom pub (XML)
  • JSON "Light" (OData v3 'de kullanıma sunuldu)
  • JSON "verbose" (OData v2)

Varsayılan olarak, Web API 'SI AtomPubJSON "Light" biçimini kullanır.

AtomPub biçimini almak için Accept üst bilgisini "Application/atom + xml" olarak ayarlayın. Örnek bir yanıt gövdesi aşağıda verilmiştir:

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

Atom biçiminin belirgin bir dezavantajına bakabilirsiniz: Bu, JSON ışığının daha ayrıntılıdır. Ancak, AtomPub 'yi anlayan bir istemciniz varsa, istemci bu biçimi JSON üzerinden tercih edebilir.

Aynı varlığın JSON hafif sürümü aşağıda verilmiştir:

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

JSON light biçimi, OData protokolünün 3. sürümünde sunulmuştur. Geriye dönük uyumluluk için, bir istemci eski "ayrıntılı" JSON biçimini talep edebilir. Ayrıntılı JSON istemek için Accept üst bilgisini application/json;odata=verboseolarak ayarlayın. Verbose sürümü aşağıda verilmiştir:

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

Bu biçim yanıt gövdesinde daha fazla meta veri getirir. Bu, bir oturumun tamamına çok fazla yük eklenebilir. Ayrıca, nesneyi "d" adlı bir özellikte sarmalayarak bir yöneltme düzeyi ekler.

Sonraki Adımlar