OpenAPI Şartnamesinden API proxy'si oluşturma | Apigee Edge

Bu eğitimde, Apigee Edge yönetim kullanıcı arayüzünü kullanarak OpenAPI Specification'dan Edge API proxy'si oluşturmayı öğreneceksiniz. API proxy'sini cURL gibi bir HTTP istemcisiyle çağırdığınızda API proxy, isteği Apigee sahte hedef hizmetine gönderir.

Open API Initiative hakkında

"The Open API Initiative (OAI), Swagger Spesifikasyonu'na dayalı, satıcıdan bağımsız bir API Açıklama Biçimi oluşturmaya, geliştirmeye ve tanıtmaya odaklanmıştır." Open API Initiative hakkında daha fazla bilgi için https://openapis.org adresini ziyaret edin.

OpenAPI Spesifikasyonu, RESTful API'yi açıklamak için standart bir biçim kullanır. JSON veya YAML biçiminde yazılan OpenAPI Spesifikasyonu, makine tarafından okunabilir ancak insanlar tarafından da kolayca okunup anlaşılabilir. Spesifikasyon, bir API'nin temel yolu, yolları ve fiilleri, başlıkları, sorgu parametreleri, işlemleri, içerik türleri, yanıt açıklamaları gibi öğelerini açıklar. Ayrıca, API belgeleri oluşturmak için genellikle OpenAPI spesifikasyonu kullanılır.

Apigee sahte hedef hizmeti hakkında

Bu eğitimde kullanılan Apigee sahte hedef hizmeti Apigee'de barındırılır ve basit veriler döndürür. API anahtarı veya erişim jetonu gerektirmez. Hatta web tarayıcısında erişebilirsiniz. Aşağıdakileri tıklayarak deneyin:

http://mocktarget.apigee.net

Hedef hizmet, selamlama Hello, guest! değerini döndürür.

Sahte hedef hizmetin desteklediği API'lerin tamamı hakkında bilgi edinmek için aşağıdakileri tıklayın:

http://mocktarget.apigee.net/help

İhtiyacınız olanlar

Apigee Edge hesabı Hesabınız yoksa Apigee Edge hesabı oluşturma bölümündeki talimatları uygulayarak kaydolabilirsiniz.
OpenAPI spesifikasyonu. Bu eğitimde, mocktarget.yaml Apigee'nin sahte hedef hizmetini açıklayan OpenAPI Spesifikasyonuhttp://mocktarget.apigee.net'nu kullanacaksınız. Daha fazla bilgi için https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi sayfasına bakın.
Komut satırından API çağrıları yapmak için makinenizde cURL yüklü olmalıdır veya bir web tarayıcısı kullanmalısınız.

API proxy'sini oluşturma

Edge

Edge kullanıcı arayüzünü kullanarak OpenAPI Specification'dan API proxy'si oluşturmak için:

https://apigee.com/edge adresinde oturum açın.
Ana pencerede API Proxies'i (API Proxy'leri) tıklayın.
Alternatif olarak, soldaki gezinme çubuğunda Geliştir > API Proxies'i seçebilirsiniz.
+ Proxy'yi tıklayın.
Proxy Oluşturma sihirbazında, Ters proxy (en yaygın) şablonu için OpenAPI Spec'i kullan'ı tıklayın.
URL'den içe aktar'ı tıklayın ve aşağıdaki bilgileri girin:
- OpenAPI Spec URL'si: URL alanındaki OpenAPI Spesifikasyonu için GitHub'daki ham içeriğin yolu:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Spec name (Özellik adı): OpenAPI Specification'ın adı (ör. Mock Target).
  Bu ad, OpenAPI spesifikasyonunu spesifikasyon deposunda saklamak için kullanılır. Spesifikasyonlarınızı yönetme başlıklı makaleyi inceleyin.

İçe Aktar'ı tıklayın.

Proxy oluşturma sihirbazındaki Ayrıntılar sayfası gösterilir. Alanlar, aşağıdaki resimde gösterildiği gibi OpenAPI spesifikasyonunda tanımlanan değerler kullanılarak önceden doldurulur.

Aşağıdaki tabloda, OpenAPI Spesifikasyonu'ndaki özellikler kullanılarak önceden doldurulmuş varsayılan değerler açıklanmaktadır. Kullanılan özellikleri gösteren OpenAPI Spesifikasyonu'nun bir alıntısı tabloyu takip etmektedir.

Alan	Açıklama	Varsayılan
Ad	API proxy'sinin adı. Örneğin: `Mock-Target-API`.	Boşlukların tirelerle değiştirildiği OpenAPI Specification'daki `title` özelliği
Temel yol	Bu API proxy'sini kuruluş içinde benzersiz şekilde tanımlayan yol bileşeni. Bu API proxy'sinin herkese açık URL'si, kuruluşunuzun adı, bu API proxy'sinin dağıtıldığı bir ortam ve bu temel yoldan oluşur. Örneğin: `http://myorg-test.apigee.net/mock-target-api`	Ad alanı içeriği tamamen küçük harfe dönüştürülür.
Açıklama	API proxy'sinin açıklaması.	OpenAPI Specification'daki `description` özelliği
Hedef (Mevcut API)	Bu API proxy'si adına çağrılan hedef URL. Herkese açık internet üzerinden erişilebilen tüm URL'ler kullanılabilir. Örneğin: `http://mocktarget.apigee.net`	OpenAPI Specification'daki `servers` özelliği

Aşağıda, alanları önceden doldurmak için kullanılan özellikleri gösteren OpenAPI Spesifikasyonu'ndan bir alıntı verilmiştir.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Açıklama alanını aşağıdaki şekilde düzenleyin: API proxy for the Apigee mock target service endpoint.
İleri'yi tıklayın.
Ortak politikalar sayfasındaki Güvenlik: Yetkilendirme bölümünde Geçiş (yetkilendirme yok) seçeneğinin belirlendiğinden emin olun ve Sonraki'yi tıklayın:
Akışlar sayfasında tüm işlemlerin seçili olduğundan emin olun.
İpucu: Koşullu akışlar, OpenAPI Spesifikasyonu'ndaki paths nesnesinde tanımlanan işlemlerden otomatik olarak oluşturulur. Koşullu akışlar, Edge'e "Bunu gördüğünüzde bu mantığı uygula" der. Örneğin, bir API çağrısı /xml kaynağında (koşul) GET olduğunda yanıtı JSON'a dönüştürün (koşullu akışa eklenen bir politika aracılığıyla). İşlem başına yalnızca bir akış yürütülür. Bu akış, koşulu doğru olarak değerlendirilen ilk akıştır.
İleri'yi tıklayın.
Sanal ana makineler sayfasında varsayılan ve güvenli'yi seçip İleri'yi tıklayın.
Özet sayfasında, İsteğe Bağlı Dağıtım bölümünde Test ortamının seçili olduğundan emin olun ve Oluştur ve dağıt'ı tıklayın:

Apigee, yeni API proxy'nizi oluşturur ve test ortamınıza dağıtır:
API proxy'sinin Genel Bakış sayfasını görüntülemek için Proxy'yi düzenle'yi tıklayın.

Classic Edge (Private Cloud)

Klasik Edge kullanıcı arayüzünü kullanarak OpenAPI Specification'dan API proxy'si oluşturmak için:

https://apigee.com/edge adresinde oturum açın.
Ana pencerede API Proxies'i (API Proxy'leri) tıklayın.
Alternatif olarak, soldaki gezinme çubuğunda Geliştir > API Proxies'i seçebilirsiniz.
+ Proxy'yi tıklayın.
Proxy oluşturma sihirbazında Ters proxy (en yaygın) seçeneğini belirleyin ve OpenAPI'yi kullan'ı tıklayın.
URL'den içe aktar'ı tıklayın, OpenAPI Spesifikasyonu için bir ad girin ve URL alanına OpenAPI Spesifikasyonu'nun GitHub'daki ham içeriğinin yolunu girin:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Seç'i tıklayın.

İleri'yi tıklayın.

Proxy oluşturma sihirbazındaki Ayrıntılar sayfası gösterilir. Alanlar, aşağıdaki şekilde gösterildiği gibi OpenAPI spesifikasyonunda tanımlanan değerler kullanılarak önceden doldurulur.

Aşağıdaki tabloda, OpenAPI Spesifikasyonu'ndaki özellikler kullanılarak önceden doldurulmuş varsayılan değerler açıklanmaktadır. Kullanılan özellikleri gösteren OpenAPI Spesifikasyonu'nun bir alıntısı tabloyu takip etmektedir.

Alan	Açıklama	Varsayılan
Proxy Adı	API proxy'sinin adı. Örneğin: `Mock-Target-API`.	Boşlukların tirelerle değiştirildiği OpenAPI Specification'daki `title` özelliği
Proxy Base Path	Bu API proxy'sini kuruluş içinde benzersiz şekilde tanımlayan yol bileşeni. Bu API proxy'sinin herkese açık URL'si, kuruluşunuzun adı, bu API proxy'sinin dağıtıldığı bir ortam ve bu temel yoldan oluşur. Örneğin: `http://myorg-test.apigee.net/mock-target-api`	Ad alanı içeriği tamamen küçük harfe dönüştürülür.
Mevcut API	Bu API proxy'si adına çağrılan hedef URL. Herkese açık internet üzerinden erişilebilen tüm URL'ler kullanılabilir. Örneğin: `http://mocktarget.apigee.net`	OpenAPI Specification'daki `servers` özelliği
Açıklama	API proxy'sinin açıklaması.	OpenAPI Specification'daki `description` özelliği

Aşağıda, alanları önceden doldurmak için kullanılan özellikleri gösteren OpenAPI Spesifikasyonu'ndan bir alıntı verilmiştir.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Açıklama alanını aşağıdaki şekilde düzenleyin: API proxy for the Apigee mock target service endpoint.
İleri'yi tıklayın.
Akışlar sayfasında tüm işlemlerin seçili olduğundan emin olun.
İpucu: Koşullu akışlar, OpenAPI Spesifikasyonu'ndaki paths nesnesinde tanımlanan işlemlerden otomatik olarak oluşturulur. Koşullu akışlar, Edge'e "Bunu gördüğünüzde bu mantığı uygula" der. Örneğin, bir API çağrısı /xml kaynağında (koşul) GET olduğunda yanıtı JSON'a dönüştürün (koşullu akışa eklenen bir politika aracılığıyla). İşlem başına yalnızca bir akış yürütülür. Bu akış, koşulu doğru olarak değerlendirilen ilk akıştır.
İleri'yi tıklayın.
Güvenlik sayfasında güvenlik seçeneği olarak Geçiş (yok)'i belirleyin ve Sonraki'yi tıklayın.
Sanal Ana Makineler sayfasında tüm sanal ana makinelerin seçili olduğundan emin olun ve Sonraki'yi tıklayın.
Derleme sayfasında test ortamının seçili olduğundan emin olun ve Derle ve Dağıt'ı tıklayın.
Özet sayfasında, yeni API proxy'nizin başarıyla oluşturulduğunu ve test ortamınıza dağıtıldığını belirten bir onay mesajı görürsünüz.
API proxy'sinin Genel Bakış sayfasını görüntülemek için Mock-Target-API'yi tıklayın.

Tebrikler! OpenAPI Specification'dan API proxy'si oluşturmuş olmanız gerekir. Ardından, nasıl çalıştığını görmek için test edersiniz.

API proxy'sini test etme

Mock-Target-API API'nizi cURL veya bir web tarayıcısı kullanarak test edebilirsiniz.

Bir terminal penceresinde aşağıdaki cURL komutunu çalıştırın. URL'de kuruluşunuzun adını girin.

curl http://<org_name>-test.apigee.net/mock-target-api

Yanıt

Aşağıdaki yanıtı görmeniz gerekir:

Hello, Guest!

Tebrikler! OpenAPI Specification'dan basit bir API proxy'si oluşturup test etmiş olmanız gerekir.

XML'den JSON'a politika ekleme

Ardından, OpenAPI Spesifikasyonu'ndan API proxy'si oluşturduğunuzda otomatik olarak oluşturulan XML Yanıtını Görüntüle koşullu akışına XML'yi JSON'a dönüştürme politikasını eklersiniz. Politika, hedefin XML yanıtını JSON yanıtına dönüştürür.

Öncelikle, sonuçları politikayı ekledikten sonra alınan sonuçlarla karşılaştırabilmek için API'yi çağırın. Bir terminal penceresinde aşağıdaki cURL komutunu çalıştırın. Hedef hizmetin /xml kaynağını çağırıyorsunuz. Bu kaynak, basit bir XML bloğunu yerel olarak döndürür. URL'de kuruluşunuzun adını kullanın.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Yanıt

Aşağıdaki yanıtı görmeniz gerekir:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Şimdi de XML yanıtını JSON'a dönüştüren bir işlem yapalım. API proxy'sindeki XML Yanıtını Görüntüle koşullu akışına XML'yi JSON'a dönüştürme politikasını ekleyin.

Edge kullanıcı arayüzündeki Mock-Target-API Overview sayfasının sağ üst köşesindeki Develop (Geliştir) sekmesini tıklayın.
Sol Gezinme bölmesinde, Proxy Uç Noktaları > varsayılan bölümünde View XML Response koşullu akışını tıklayın.
Akışın Yanıt'ına karşılık gelen alttaki +Adım düğmesini tıklayın.

Ekleyebileceğiniz tüm politikaların kategorilere ayrılmış listesini göstermek için Adım Ekle iletişim kutusu açılır.
Aracılık kategorisine gidin ve XML to JSON'ı (XML'den JSON'a) seçin.
Görünen ad ve Ad için varsayılan değerleri koruyun.
Ekle'yi tıklayın. XML'den JSON'a politikası yanıta uygulanır.
Kaydet'i tıklayın.

Politikayı eklediğinize göre, cURL kullanarak API'yi tekrar çağırın. Aynı /xml kaynağını çağırmaya devam ettiğinizi unutmayın. Hedef hizmet, XML bloğunu döndürmeye devam eder ancak API proxy'sindeki politika artık yanıtı JSON'a dönüştürür. Şu aramayı yapın:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

XML yanıtının JSON'a dönüştürüldüğünü unutmayın:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Tebrikler! Koşullu akışa eklenen bir politikanın yürütülmesini başarıyla test ettiniz.