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'si, isteği Apigee örnek hedef hizmetine gönderir.

Open API Initiative hakkında

"Open API Initiative (OAI), Swagger Specification'a dayalı olarak tedarikçiden 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 adresine bakın.

OpenAPI Spesifikasyonu, bir RESTful API'yi tanımlamak için standart bir biçim kullanır. JSON veya YAML biçiminde yazılan OpenAPI Spesifikasyonu, makine tarafından da okunabilse de insanlar tarafından kolayca okunup anlaşılabilir. Spesifikasyonda, bir API'nin temel yolu, yolları ve fiilleri, başlıkları, sorgu parametreleri, işlemleri, içerik türleri, yanıt açıklamaları ve daha fazlası yer alır. Ayrıca, API belgeleri oluşturmak için yaygın olarak 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. Aslına bakılırsa, bu içeriğe bir web tarayıcısından erişebilirsiniz. Aşağıdakileri tıklayarak deneyin:

http://mocktarget.apigee.net

Hedef hizmet, Hello, guest! karşılama mesajını döndürür

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

http://mocktarget.apigee.net/help

Gerekenler

Apigee Edge hesabı. Hesabınız yoksa Apigee Edge hesabı oluşturma sayfasındaki talimatları uygulayarak kaydolabilirsiniz.
OpenAPI Belirtimi. Bu eğiticide, Apigee'nin örnek hedef hizmeti olan http://mocktarget.apigee.net'yi açıklayan mocktarget.yaml OpenAPI Spesifikasyonunu kullanacaksınız. Daha fazla bilgi için https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi inceleyin.
Komut satırından API çağrıları yapmak için makinenize cURL veya bir web tarayıcısı yükleyin.

API proxy'si oluşturma

Edge

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

https://apigee.com/edge adresinde oturum açın.
Ana pencerede API Proxy'leri seçeneğini tıklayın.
Alternatif olarak, sol gezinme çubuğunda Geliştir > API Proxy'leri öğesini de seçebilirsiniz.
+ Proxy'yi tıklayın.
Proxy Oluştur sihirbazında, Ters proxy (en yaygın) şablonu için OpenAPI Özelliğini Kullan'ı tıklayın.
URL'den içe aktar'ı tıklayın ve aşağıdaki bilgileri girin:
- OpenAPI Spec URL: URL alanında OpenAPI Specification 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
```
- Spesifikasyon adı: OpenAPI Spesifikasyonu'nun adı (ör. Örnek Hedef).
  Bu ad, OpenAPI Specification'ı spesifikasyon deposunda depolamak 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örüntülenir. Alanlar, aşağıda gösterildiği gibi OpenAPI Specification'da tanımlanan değerler kullanılarak önceden doldurulur

Aşağıdaki tabloda, OpenAPI Specification'daki özellikler kullanılarak önceden doldurulmuş varsayılan değerler açıklanmaktadır. Aşağıdaki tabloda, kullanılan mülkleri gösteren OpenAPI Specification'dan bir alıntı gösterilmektedir.

Alan	Açıklama	Varsayılan
Ad	API proxy'sinin adı. Örneğin: `Mock-Target-API`.	OpenAPI Spesifikasyonu'ndan, boşluklarla değiştirilmiş `title` mülkü
Temel yol	Kuruluş içinde bu API proxy'sini 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 tamamı küçük harfe dönüştürüldü
Açıklama	API proxy'sinin açıklaması.	OpenAPI Specification'dan `description` mülk
Hedef (Mevcut API)	Bu API proxy'si adına çağrılan hedef URL. Açık internet üzerinden erişilebilen herhangi bir URL kullanılabilir. Örneğin: `http://mocktarget.apigee.net`	OpenAPI Specification'dan `servers` mülk

Aşağıda, alanları önceden doldurmak için kullanılan özellikleri gösteren OpenAPI Specification'dan 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ı şu şekilde düzenleyin: API proxy for the Apigee mock target service endpoint.
İleri'yi tıklayın.
Genel politikalar sayfasında, Güvenlik: Yetkilendirme altında, Geçiş (yetkilendirme yok) seçeneğinin belirlendiğinden emin olun ve İ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 Specification'daki paths nesnesinde tanımlanan işlemlerden otomatik olarak oluşturulur. Koşullu akışlar Edge'e "Bunu gördüğünüzde şu mantığı uygulayın" deyin. Örneğin, bir API çağrısı /xml kaynağında (koşul) bir GET olduğunda (koşul) yanıtı JSON'a dönüştürün (koşullu akışa ekli 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.
Virtual hosts (Sanal ana makineler) sayfasında default (varsayılan) ve secure'yi (güvenli) seçip Next'i (İleri) tıklayın.
Özet sayfasında, İsteğe Bağlı Dağıtım altında 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.

Klasik Edge (Private Cloud)

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

https://apigee.com/edge adresinde oturum açın.
Ana pencerede API Proxy'leri seçeneğini tıklayın.
Alternatif olarak, sol gezinme çubuğunda Geliştir > API Proxy'leri öğesini de seçebilirsiniz.
+ Proxy'yi tıklayın.
Proxy Oluştur sihirbazında, Ters proxy (en yaygın) seçeneğini belirleyin ve OpenAPI'yi Kullan'ı tıklayın.
Bir URL'den içe aktar'ı tıklayın, OpenAPI Spesifikasyonu için bir ad girin ve GitHub'daki OpenAPI Specification için ham içeriğin yolunu URL alanına 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örüntülenir. Alanlar, aşağıdaki şekilde gösterildiği gibi OpenAPI Specification'da tanımlanan değerler kullanılarak önceden doldurulur.

Aşağıdaki tabloda, OpenAPI Specification'daki özellikler kullanılarak önceden doldurulmuş varsayılan değerler açıklanmaktadır. Aşağıdaki tabloda, kullanılan mülkleri gösteren OpenAPI Specification'dan bir alıntı gösterilmektedir.

Alan	Açıklama	Varsayılan
Proxy Adı	API proxy'sinin adı. Örneğin: `Mock-Target-API`.	OpenAPI Spesifikasyonu'ndan, boşluklarla değiştirilmiş `title` mülkü
Proxy Temel Yolu	Kuruluş içinde bu API proxy'sini 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 tamamı küçük harfe dönüştürüldü
Mevcut API	Bu API proxy'si adına çağrılan hedef URL. Açık internet üzerinden erişilebilen herhangi bir URL kullanılabilir. Örneğin: `http://mocktarget.apigee.net`	OpenAPI Specification'dan `servers` mülk
Açıklama	API proxy'sinin açıklaması.	OpenAPI Specification'dan `description` mülk

Aşağıda, alanları önceden doldurmak için kullanılan özellikleri gösteren OpenAPI Specification'dan 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ı şu ş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 Specification'daki paths nesnesinde tanımlanan işlemlerden otomatik olarak oluşturulur. Koşullu akışlar Edge'e "Bunu gördüğünüzde şu mantığı uygulayın" deyin. Örneğin, bir API çağrısı /xml kaynağında (koşul) bir GET olduğunda (koşul) yanıtı JSON'a dönüştürün (koşullu akışa ekli 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) seçeneğini belirleyin ve İleri'yi tıklayın.
Sanal Ana Makineler sayfasında tüm sanal ana makinelerin seçili olduğundan emin olun ve İleri'yi tıklayın.
Derleme sayfasında test ortamının seçili olduğundan emin olun ve Derleme ve Dağıt'ı tıklayın.
Özet sayfasında, yeni API proxy'nizin başarıyla oluşturulduğu ve test ortamınıza dağıtıldığına dair bir onay görürsünüz.
API proxy'sinin Genel Bakış sayfasını görüntülemek için Örnek-Hedef-API'yi tıklayın.

Tebrikler! OpenAPI Specification'dan bir API proxy'si oluşturdunuz. Ardından, nasıl çalıştığını görmek için test edin.

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ı yazın.

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 derleyip test ettiniz.

JSON politikasına XML ekleme

Ardından XML'i, OpenAPI Specification'dan API proxy'si oluşturduğunuzda otomatik olarak oluşturulan XML Yanıtı Görüntüleme koşullu akışına XML'ye eklersiniz. Politika, hedefin XML yanıtını bir JSON yanıtına dönüştürür.

İlk olarak API'yi çağırarak sonuçları politikayı ekledikten sonra alınan sonuçlarla karşılaştırabilirsiniz. Bir terminal penceresinde aşağıdaki cURL komutunu yürütün. Hedef hizmetin basit bir XML bloğunu yerel olarak döndüren /xml kaynağını çağırıyorsunuz. URL'de kuruluşunuzun adını yazı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 XML yanıtını JSON'a dönüştüren bir işlem yapalım. XML'yi JSON'a, API proxy'sinde XML Yanıtı Görüntüleme koşullu akışına ekleyin.

Edge kullanıcı arayüzündeki Mock-Target-API'ye Genel Bakış sayfasının sağ üst köşesindeki Geliştir sekmesini tıklayın.
Sol Gezgin bölmesinde, Proxy Uç Noktaları > varsayılan bölümünün altında XML Yanıtını Görüntüle koşullu akışını tıklayın.
Akışa ilişkin Yanıt'a karşılık gelen alt taraftaki +Adım düğmesini tıklayın.

Ekleyebileceğiniz tüm politikaların kategorize edilmiş listesini görüntülemek için Adım Ekle iletişim kutusu açılır.
Uyumlulaştırma kategorisine gidin ve XML'den JSON'a seçeneğini belirleyin.
Görünen Ad ve Ad için varsayılan değerleri koruyun.
Ekle'yi tıklayın. Yanıta XML'den JSON'a geçiş politikası uygulanır.
Kaydet'i tıklayın.

Politikayı eklediğinize göre cURL kullanarak API'yi tekrar çağırın. Hâlâ aynı /xml kaynağını çağırdığınıza dikkat edin. Hedef hizmet, XML bloğunu döndürmeye devam eder ancak API proxy'sindeki politika yanıtı JSON'a dönüştürür. Bu 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.