API'leri belgelemek için SmartDokümanlar'ı kullanma

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

SmartDokümanlar, API belgelerini Drupal 7 geliştirici portalında, API belgelerini tamamen etkileşimli hale getirecek şekilde belgelemenize olanak tanır. Etkileşimli belgeler sayesinde portal kullanıcıları şunları yapabilir:

  • API'leriniz hakkında bilgi edinin
  • API'nize canlı istek gönderme
  • API'den döndürülen canlı yanıtı görüntüleme

API'lerinizde etkileşimli belgeler oluşturarak portal kullanıcısının API'lerinizi öğrenmesini, test etmesini ve değerlendirmesini kolaylaştırırsınız.

Edge Management API, herhangi bir HTTP istemcisini kullanarak API Hizmetleri'ne erişmenizi sağlayan bir RESTful API'dir. Apigee, SmartDokümanlar'ı kullanarak Edge Management API için etkileşimli belgeler oluşturur. Buradaki API belgelerine bakın.

SmartDokümanlar portalı örneği

SmartDokümanlar'ı kullanmak için bir Apigee Geliştirici Hizmetleri portalınız olmalıdır. Daha fazla bilgi için Geliştirici portalı oluşturma bölümüne bakın.

Geliştirici portalı ana sayfanızdan, API Belgeleri sayfasını görüntülemek için üst gezinme çubuğundaki API'ler seçeneğini tıklayın.

Portalda iki API belgelenmiştir: Hello World ve Pet Store Örneği.

Hello World API, örnek hedef OpenAPI Spesifikasyonu olan mocktarget.yaml kullanılarak oluşturulmuştur. Daha fazla bilgi için https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi adresini ziyaret edin.

Pet Store Example API, klasik evcil hayvan mağazası demodan oluşturulmuştur.

Hello World API'yi keşfedin:

  1. Hello World API'yi tıklayın. Hello World API özet sayfası görüntülenir:
  2. API onayını görüntüle'yi tıklayın. Bu kaynağın SmartDokümanlar dosyası şu şekilde gösterilmektedir:
  3. Bu isteği gönder'i tıklayın.
  4. Döndürülen yanıtı görüntüleyin: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. İsteği görüntülemek için İstek sekmesini, ilgili cURL çağrısını görüntülemek içinse cURL sekmesini tıklayın.

SmartDokümanlar'ı kullanarak API'lerinizi belgeleme

SmartDokümanlar, API'lerinizi bir model kullanarak temsil eder. Bu modelde, model API'lerinizle ilgili tüm bilgileri içerir. Portal, portaldaki doküman sayfalarını Drupal düğümleri olarak oluşturmak için modelden API'lerinizle ilgili bilgileri ayıklar. Her Drupal düğümü, portaldaki bir belge sayfasına karşılık gelir.

SmartDokümanlar'ı kullanmak için izlediğiniz genel adımlar şunlardır:

  1. Portalda Drupal SmartDokümanlar modülünü yapılandırın.
  2. Bir SmartDokümanlar modeli oluşturun.
  3. API'leri modele bir WADL dosyasından, OpenAPI (eski adıyla Swagger) spesifikasyonundan veya manuel olarak ekleyin.
  4. Modeli Drupal düğümleri koleksiyonu olarak oluşturun. Her Drupal düğümü, tek bir API ile ilgili bilgiler içerir. Örneğin, API'nizdeki bir kaynak hem POST hem de PUT isteğini destekliyorsa SmartDokümanlar POST ve PUT için ayrı bir Drupal düğümü oluşturur.
  5. Drupal düğümlerini yayınlayın. Yayınlandıktan sonra portal kullanıcılarınız API'nizi görüntüleyebilir ve API ile etkileşimde bulunabilir.
  6. Drupal düğümlerini yayınlamadan önce veya yayınladıktan sonra düzenleyin. Drupal düğümlerini, Drupal düzenleyicisini kullanarak veya orijinal WADL dosyasını ya da OpenAPI Specification'ı düzenleyerek düzenleyebilirsiniz. WADL dosyasını veya OpenAPI Specification'ı düzenlemeyi tamamladığınızda, dosyayı yeni bir düzeltme olarak modele geri aktarın, ardından değişikliklerinizi oluşturup yayınlayın.
  7. TLS'yi etkinleştirin. SmartDokümanlar API'lerinize istekte bulunmanın bir parçası olarak arka ucunuza kimlik doğrulama bilgileri gönderebildiğinden bu kimlik bilgilerinin güvenli olduğundan emin olmak için portalınızda TLS'yi etkinleştirmeniz gerekir. Apigee, portal üretim ve test ortamlarında https:// istekleri yapmak için gereken TLS sertifikasını sağlar. Ancak portalınızı yayınlamadan önce kendi TLS sertifikanızı almanız ve TLS'yi etkinleştirmeniz gerekir. Daha fazla bilgi için Portalda TLS'yi kullanma bölümüne bakın.

SmartDoc modelleri ve şablonları hakkında

Portalınızda bir model oluşturduğunuzda model aslında Drupal'da değil, Edge kuruluşunuzda depolanır. Model, dahili adı olan büyük bir JSON bloğudur ("my-smartdocs-api" gibi) ve API'nin yapısını tanımlar. Öte yandan portalınız, modeli HTML'de oluşturur ve model için düzenleme arayüzü sağlar. Portaldaki API'de yapılan güncellemeler, otomatik olarak kaynak modele geri aktarılır.

Kuruluşta depolanıyor

Drupal'da depolanıyor

modeller

Şablonlar

Düzenleme işlevine sahip Drupal düğümler

Kuruluşunuzda birden fazla portal (ör. geliştirme, aşama ve üretim) olduğunu varsayalım. Pantheon'da, bir portalı bir ortamdan diğerine taşırsınız. Portalın her örneği kendi modelini içeriyormuş gibi görünüyor ancak tüm örnekler aslında kaynak modeli referans alıyor. API'yi geliştirme aşamasında düzenlerseniz model güncellenir ve değişiklikler üretimde görünür. Benzer şekilde, geliştirme aşamasındaki bir modeli silerseniz kaynak da silinir ve artık üretimde kullanılamaz.

Şablonlar, SmartDokümanlar'ınızın görünümünü ve tarzını kontrol eder. Bu şablonlar (Herkese açık adres çubuğu ve CSS dosyaları) her portal örneğiyle birlikte depolanır. Böylece her portal teorik olarak her model için benzersiz bir şablon kullanabilir. Ancak oluşturma çerçevesinin avantajlarından biri, her modele varsayılan şablonun (Apigee varsayılanı veya sağladığınız bir şablon) otomatik olarak uygulanmasıdır.

Aşağıdaki şemada, modeller ve portallar arasındaki ilişki gösterilmektedir. Yeşil oklar otomatik senkronizasyonu gösterir.

Aşağıdaki cURL komutu, kuruluşunuzdaki tüm modelleri listeler:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

SmartDokümanlar modülünü yapılandırma

Apigee, SmartDokümanlar'ı özel bir Drupal modülü olarak kullanmaya başladı. SmartDokümanlar modülünü yapılandırmak için aşağıdaki prosedürü uygulayın.

SmartDokümanlar modülünü yapılandırmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde Modüller'i seçin. Yüklü tüm Drupal modüllerinin listesi görüntülenir.
  3. SmartDocs modülünü etkinleştirin.
  4. Yapılandırmayı kaydedin.
  5. Drupal yönetici menüsünde Modüller'i seçin.
  6. SmartDokümanlar -> İzinler'i seçin ve "Yönetici" rolünün "SmartDokümanlar modülü için yönetim görevlerini gerçekleştir" seçeneğinin etkinleştirildiğinden emin olun.
  7. Drupal yönetim menüsünde Yapılandırma > Geliştirici Portalı'nı seçin.
  8. Bağlantı Zaman Aşımı ve İstek Zaman Aşımı'nı 16 saniye olarak ayarlayın.
  9. Yapılandırmayı kaydedin.
  10. URL ayarlarını yapılandırın:
    1. Drupal menüsünden Yapılandırma > Arama ve meta veriler > URL takma adları > Ayarlar'ı seçin.
    2. Maksimum takma ad uzunluğu ve Maksimum bileşen uzunluğu ayarlarını 255 olarak ayarlayın.
    3. Noktalama işaretleri'ni genişletin.
    4. Sol kıvrık ayraç ({) ve Sağ kıvrık ayraç (}) ayarları için İşlem yok (değiştirme) seçeneğini belirleyin.
    5. Save configuration'ı (Yapılandırmayı kaydet) tıklayın.
  11. Geliştirici portalınız, internet erişimi olmayan dahili bir ağdaki kullanıcılara gösterilecekse veya API'lerinizin bir alt kümesi özel bir ağdaysa SmartDokümanlar API proxy URL'sini aşağıdaki gibi yapılandırın:
    1. Drupal Yönetim menüsünde Yapılandırma > SmartDokümanlar'ı seçin.
    2. Gelişmiş Ayarlar'ı genişletin.
    3. SmartDokümanlar proxy URL'si alanını aşağıdaki şekilde güncelleyin: <host>/smartdocs/v1/sendrequest.
      Satır içi yardım, ortamınız için gerekli değeri sağlamalıdır. Örneğin:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      Bu alanın varsayılan değeri https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Save configuration'ı (Yapılandırmayı kaydet) tıklayın.

Model oluşturma

Model, API'nizin temsiliyle ilgili tüm bilgileri içerir. Portalda farklı API'leri desteklemek için birden fazla model tanımlayabilir veya tüm API'lerinizi tek bir modelde gruplandırabilirsiniz.

Her model, oluşturulan Drupal düğümlerinin temel URL'sini de tanımlayan benzersiz bir dahili ad belirtir. Her Drupal düğümünün URL'si şu biçimdedir:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

Bu örnekte:

  • drupalBasePath: Portalınızın temel URL'si.
  • internalName: Modelin dahili adı.
  • httpMethod: API'nin HTTP yöntemidir (ör. alma, koyma, yayınlama veya silme).
  • resourcePath: Kaynak yolu.

Örneğin, dahili adı "mymodel" olarak belirtirseniz "/books" adlı bir kaynağa yapılan GET isteği için oluşturulan Drupal düğümünün URL'si şu olur:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Model oluşturmak için

Bir model oluşturduğunuzda bu model, API yapısının kaynağı olarak Edge kuruluşunuzda depolanır. Daha fazla bilgi için SmartDoc modelleri ve şablonları hakkında başlıklı makaleyi inceleyin.

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Sayfanın üst kısmında Yeni model'i seçin.
  4. Aşağıdaki alanları girin:
    • Ad: Site genelinde görüntülenecek model adı.
    • Dahili ad: Ad yazarken dahili ad görüntülenir. Modelin, tüm modeller arasında benzersiz olması gereken dahili adı. Dahili ad yalnızca küçük harf, rakam ve boşluk içermeyen kısa çizgi içermelidir. Bu adı düzenlemek için Düzenle'yi seçin.
    • Açıklama: Modelin açıklaması.
  5. Model Oluştur'u seçin.

Modeli oluşturduktan sonra model sayfasına yönlendirilirsiniz. Buradan, İşlemler açılır menüsünü kullanarak şunları yapabilirsiniz:

  • API'nizi açıklayan bir WADL dosyasını içe aktarın veya API'nizi açıklayan bir OpenAPI Specification'ın URL'sini belirtin.
  • Modele Düzeltme Ekle
  • Model tarafından kullanılan stil sayfaları da dahil olmak üzere modelin Ayarlar'ını değiştirin.
  • Modeli bir dosyaya aktarın.
  • Modeli silin.

Bir modele API ekleme

Bir modele API'leri şu şekilde ekleyebilirsiniz:

  • API tanımını içeren bir WADL dosyasını içe aktarma
  • OpenAPI Spesifikasyonunu İçe Aktarma (OpenAPI 2.0 veya 1.2)
  • Kaynakları ve yöntemleri manuel olarak oluşturma

Ayrıca, SmartDokümanlar JSON dosyasını bir modele aktarabilirsiniz. Bu dosya genellikle önce mevcut bir model dışa aktarılıp dosyanın düzenlenmesi ve ardından güncellemelerin içe aktarılmasıyla oluşturulur. Daha fazla bilgi için aşağıdaki "Modeli dışa ve içe aktarma" bölümüne bakın.

Video: OpenAPI Specification'ı içe aktararak bir SmartDokümanlar modeline API'leri nasıl ekleyeceğinizi öğrenmek için kısa bir video izleyin.

WADL içe aktarma

Bir modeli başarıyla oluşturduktan sonra, API'nizi açıklayan bir WADL dosyasını içe aktarın. Bir WADL dosyasını her içe aktardığınızda otomatik olarak modelin yeni bir düzeltmesini oluşturursunuz.

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz modeli seçin.
  4. İşlemler bölümünde İçe aktar'ı seçin.
  5. SmartDokümanlar içe aktarma sayfasındaki Biçim Seç açılır listesinde WADL'yi seçin.
  6. Yükleme Türü açılır listesinde Dosya veya URL'yi seçin.
    1. Dosya'yı seçerseniz WADL dosyasına gidin.
    2. URL'yi seçerseniz WADL dosyasının URL'sini belirtin.
  7. Öğeyi modele aktarmak için İçe aktar'ı tıklayın. Artık modeli oluşturabilirsiniz.
  8. Artık modeli oluşturabileceğiniz model bilgi sayfasına yönlendirilirsiniz.

OpenAPI Spesifikasyonunu İçe Aktarma

Modeli başarıyla oluşturduktan sonra OpenAPI (eski adıyla Swagger) Spesifikasyonunu içe aktarabilirsiniz. Edge, OpenAPI 1.2 ve 2.0 sürümlerini destekler.

OpenAPI, bir API'yi tanımlamak için JSON nesneleri içeren dosyaları kullanır. Bir OpenAPI Specification'ı içe aktardığınız her seferde, otomatik olarak modelin yeni bir düzeltmesini oluşturursunuz.

OpenAPI Spesifikasyonunu içe aktarmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz modeli seçin.
  4. İşlemler bölümünde İçe aktar'ı seçin.
  5. SmartDokümanlar içe aktarma sayfasındaki Biçim Seç açılır menüsünde Swagger JSON veya Swagger YAML'yi seçin.
  6. Yükleme Türü açılır listesinde Dosya veya URL'yi seçin (OpenAPI 1.2 için URL'yi seçmeniz gerekir).
    1. Dosya'yı seçerseniz OpenAPI Spesifikasyonu'na gidin.
    2. URL'yi seçerseniz OpenAPI Spesifikasyonu'nun URL'sini belirtin.
  7. Öğeyi modele aktarmak için İçe aktar'ı tıklayın.
  8. Artık modeli oluşturabileceğiniz model bilgi sayfasına yönlendirilirsiniz.

Kaynakları ve yöntemleri manuel olarak oluşturma

API'nizi temsil eden bir WADL dosyanız veya OpenAPI Spesifikasyonu yoksa modelinize manuel olarak API ekleyebilirsiniz. Ayrıca, modelinizi oluşturmak için bir WADL dosyası veya OpenAPI Specification kullanıyorsanız içe aktarma işleminden sonra yeni API'ler eklemek de dahil olmak üzere API'lerinizi düzenlemek için bu prosedürü kullanabilirsiniz.

Manuel olarak API eklemek için:

  1. Modelin yeni bir düzeltmesini oluşturun.

    Düzeltmeyi oluştururken modeldeki tüm API'lerin tek temel yolunu belirtirsiniz. Diğer bir deyişle, bir modeldeki tüm API'ler aynı temel yolu paylaşır. Örneğin, temel yolu şu şekilde belirtin:

    https://myCompany.com/v1

    Modele kaynak eklediğinizde bunlar temel yolu genişletir.
  2. Model için bir veya daha fazla kaynak tanımlayın. Kaynak yolu, kaynağın tam URL'sini belirtmek için model düzeltmesinin temel yoluyla birleştirilir. Örneğin, kaynağınız bir "/login" yolunu tanımlıyorsa kaynağın tam URL'si şu şekildedir:

    https://myCompany.com/v1/login
  3. Her kaynak için bir veya daha fazla yöntem tanımlayın. Yöntem, bir kaynakta çağrılabilecek HTTP fiilini belirtir. Örneğin, "/login" kaynağı için giriş yapmak üzere POST'u, çıkış için DELETE'i destekliyorsunuzdur. Bu kaynak, PUT veya GET gibi diğer HTTP fiillerini desteklemiyor. Bu nedenle, kaynak için biri POST ve diğeri DELETE için olmak üzere iki yöntem tanımlayın.

    Yöntem, üst kaynağındaki kaynak URL'sini kullanır. Bu nedenle, aynı URL'ye sahip tüm yöntemler SmartDokümanlar'da tek bir kaynak altında tanımlanır.

Genel kural olarak:

  • API'nizdeki her benzersiz temel yol için farklı bir SmartDokümanlar modeli oluşturun.
  • API'nizdeki her benzersiz kaynak için farklı bir SmartDokümanlar kaynağı tanımlayın.
  • Bir kaynak tarafından desteklenen her HTTP fiili için farklı bir SmartDokümanlar yöntemi tanımlayın.

Modelin yeni bir düzeltmesini oluşturma

Yalnızca bir modelin mevcut düzeltmesine kaynak ekleyebilirsiniz. Modelde halihazırda bir düzeltme varsa kaynağınızı ekleyebilirsiniz. Model yeniyse ve hiçbir düzeltme yoksa yeni bir düzeltme oluşturun.

Bir modelin yeni düzeltmesini oluşturmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz model için İşlemler bölümünden Düzeltme Ekle'yi seçin.
  4. API Düzeltmesi Ekle sayfasında aşağıdaki bilgileri girin:
    • Görünen Ad: Düzeltmenin portalda görünen adı.
    • Sürüm kimliği: Düzeltme için kısa bir tanımlayıcı.
    • Açıklama: Düzeltmenin açıklaması.
    • Base URL (Temel URL): Modelin revizyonundaki tüm API'lerin temel URL'si. Modeller, her düzeltme için farklı temel URL'ler kullanabilir. Örneğin, temel URL'ye bir sürüm göstergesi eklersiniz. İlk model düzeltmesi için temel URL şu şekildedir:
      https://myCompany.com/v1
      Bir sonraki düzeltme için temel URL şöyle olabilir:
      https://myCompany.com/v2
  5. Düzeltme Ekle'yi seçin. Modelin düzeltme sayfasına yönlendirilirsiniz. Artık model üzerinde kaynakları tanımlayabilirsiniz.

Kaynağı tanımlama

Kaynak, bir API'nin tam URL'sini belirtir. Bir kaynağı tanımlarken, kaynağın tam URL'sini oluşturmak için model düzeltmesinde temel URL ile birleştirilen kaynak yolunu belirtirsiniz.

Bir kaynak tanımlamak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > Akıllı Dokümanlar'ı seçin.
  3. Güncellemek istediğiniz modelin tüm düzeltmelerini görüntülemek için İşlemler altında API Düzeltmeleri'ni seçin.
  4. Düzenlemek için bir düzeltme seçin.
  5. Düzeltme sayfasında, açılır menüden Kaynak Ekle'yi seçin.
  6. Kaynak Ekle sayfasında aşağıdaki bilgileri girin:
    • Display Name (Görünen Ad): Kaynağın adı.
    • Yol: "/" ile başlayan kaynak yolu. Yol değeri, kaynağın tam URL'sinin oluşturulması için model düzeltmesinin Temel URL'si ile birleştirilir.
    • Açıklama: Kaynağın açıklamasıdır.
    • Parametreler: İsteğe bağlı olarak kaynaktaki her parametreyi tanımlayan JSON nesnesini girin. Bu parametreler aşağıda açıklanmıştır.
  7. Kaynak Ekle'yi seçin. Model sayfasına yönlendirilirsiniz. Artık kaynakta yöntemler tanımlayabilirsiniz.

Dilerseniz kaynağa şablon, sorgu ve başlık parametreleri gibi parametreler ekleyebilirsiniz. Tüm kaynak parametreleri, söz konusu kaynakta tanımlanan yöntemler tarafından devralınır. Bu nedenle, kaynakta bir sorgu parametresi tanımlarsanız bu kaynağa eklenen tüm yöntemler söz konusu sorgu parametresini desteklemelidir.

Alternatif olarak, bir yöntemde parametreler tanımlayabilirsiniz. Örneğin bir POST yöntemi, DELETE yönteminin desteklemediği sorgu parametrelerini destekleyebilir. Dolayısıyla, yöntemi tanımlarken aşağıda açıklandığı gibi bir yönteme özel parametreleri ekleyin.

Aşağıdaki resimde, Apigee Onayla veya İptal Et Geliştirici Uygulaması API'si için her parametre türünün vurgulandığı mevcut bir SmartDokümanlar sayfası gösterilmektedir:

Her parametre türü bir JSON nesnesi tarafından tanımlanır:

Tür

JSON nesnesi

Notlar

Şablon

{
"dataType": "string",
"defaultValue": "",
"description": "Kuruluş adı.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

Şablon parametreleri her zaman gerekli olduğundan required değerini true olarak ayarlayın ve değeri defaultValue olarak çıkarın.

Kullanıcı, SmartDokümanlar sayfasındaki URL'nin üzerine geldiğinde pop-up pencerede description değeri görünür.

Sorgu

{
"dataType": "string",
"defaultValue": "",
"description": "Konum.",
"name": "w",
"required": true,
"type": "QUERY"
}

Gerekli sorgu parametreleri yine de bir defaultValue değeri belirtebilir, ancak genellikle belirtmez.

İsteğe bağlı sorgu parametreleri için required değerini false olarak ayarlayıp defaultValue değerini belirtin.

Başlık

{
"dataType": "string",
"defaultValue": "application/json",
"description": "<code>uygulama/json</code> olarak belirtin.",
"name": "Content-Type",
"required": true,
"type": "HEADER"
}

Açıklamada HTML etiketlerini nasıl kullanabileceğinize dikkat edin.

Şablon parametresi, kaynak yolundaki bir değişkeni tanımlar. Örneğin, kaynakta iki şablon parametresi tanımlarsınız. Parametre dizisindeki her parametre tanımının virgülle ayrıldığına dikkat edin:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Daha sonra, "{}" içinde yer alan kaynak Yol tanımındaki şablon parametrelerini kullanabilirsiniz. Örneğin, yolu şu şekilde ayarlayabilirsiniz:

/login/{org_name}/{developer_email}

SmartDokümanlar API sayfasında istek gönderilebilmesi için kullanıcının, URL'yi düzenleyerek org_name ve org_name bölümünü belirtmesi gerekir.

Yöntem tanımlama

Her kaynak için bir veya daha fazla yöntem tanımlayın. Yöntem tanımı, kaynakta çağrılabilecek bir HTTP fiili belirtir. Bir kaynak üzerinde tek bir yöntem veya birden fazla yöntem tanımlanmış olabilir.

Yöntemi tanımlamanın bir parçası olarak, sorgu ve başlık parametreleri dahil olmak üzere yöntem tarafından kullanılan tüm parametreleri belirtin. Bir yönteme parametre eklemeyle ilgili bilgi için yukarıdaki açıklamaya bakın.

Aşağıdaki resimde, Apigee Create Developer API için mevcut bir SmartDokümanlar sayfası gösterilmektedir. Bu sayfa, bir yöntem tanımlarken belirlediğiniz değerle vurgulanmıştır:

Sonraki resimde aynı sayfa, İstek Gövdesinin Açıklaması seçili olarak gösteriliyor:

Bir yöntem tanımlamak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz modelin tüm düzeltmelerini görüntülemek için İşlemler altında API Düzeltmeleri'ni seçin.
  4. Düzenlemek için bir düzeltme seçin.
  5. Düzeltme sayfasında, kaynaklardan birinin açılır menüsünden Yöntem Ekle'yi seçin.
  6. Yöntemi Düzenle sayfasında aşağıdaki bilgileri girin:
    • Görünen Ad: API'nin adı. Bu ad, API için Drupal sayfasının başlığı da olur.
    • Açıklama: API'yi açıklayın.
    • Yöntem fiil: HTTP fiil türü.
    • Güvenlik Düzenleri: Yöntem için varsa kimlik doğrulama modunu belirtin. Daha fazla bilgi için SmartDokümanlar kimlik doğrulama türünü yapılandırma bölümüne bakın.
    • İçerik Türü: İsteğin ve yanıtın içerik türü. Farklı kimlik doğrulama yöntemlerini yapılandırmayla ilgili aşağıdaki bölüme bakın.
    • Parametreler: (İsteğe bağlı) Yönteme ait herhangi bir sorgu veya başlık parametresi. Daha fazla bilgi için kaynağa parametre eklemeyle ilgili yukarıdaki açıklamaya bakın.
    • İstek Gövdesi Dokümanları: (İsteğe bağlı) İstek gövdesini açıklayın. POST ve PUT yöntemleri bir istek gövdesi alır. Ürünü tanımlamak için bu alanı kullanabilirsiniz. Bu değeri atlarsanız İstek Gövdesi altındaki Açıklama bağlantısı, oluşturulan SmartDokümanlar sayfasından çıkarılır.
    • İstek Gövdesi Örneği: (İsteğe bağlı) İstek gövdesinin bir örneğini (genellikle JSON nesnesi veya XML olarak) gösterin. POST ve PUT fiilleri için her isteğin bir parçası olarak İstek Gövdesi Örneği iletilir. SmartDokümanlar sayfasının kullanıcıları API'ye istek göndermeden önce bu örneği düzenler. Bu değeri çıkarırsanız İstek Gövdesi altındaki Değer bağlantısı, oluşturulan SmartDokümanlar sayfasından çıkarılır.
    • Etiketler: API ile ilişkilendirilmiş etiket dizisi. SmartDokümanlar, benzer API'leri bir arada gruplandırmak için etiketler kullanır. Örneğin, "İstatistikler" etiketini istatistiklerle ilgili tüm API'lere uygulayabilirsiniz. Farklı kaynaklardaki API'leri, hepsi aynı etiketi kullanıyorsa tek bir etiket altında gruplandırabilirsiniz.
  7. Yöntem Ekle'yi seçin. Model sayfasına yönlendirilirsiniz. Artık yönteminizi oluşturabilir ve yayınlayabilirsiniz.

Model oluşturma

Bir modele API'ler ekledikten sonra modeli oluşturabilirsiniz. Oluşturma işlemi, modelin API ile ilgili açıklamasını Drupal düğümlerine dönüştürür. Oluşturma işlemi tamamlandığında, her API için tek bir Drupal düğümünüz olur. Burada her Drupal düğümü bir HTML sayfasına karşılık gelir.

Modelin tamamını tek seferde oluşturmayı veya oluşturma için tek tek API'leri seçmeyi tercih edebilirsiniz.

Bir model oluşturmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Oluşturmak istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Oluşturmak istediğiniz düzeltmeyi seçin. Yalnızca modelin tek bir düzeltmesinden düğüm oluşturabilirsiniz.
  5. Oluşturma yöntemlerini seçin.
  6. Güncelleme seçenekleri açılır menüsünden Düğüm Oluştur'u seçin.
  7. Güncelle'yi tıklayın.
  8. Oluşturulan düğümlerinizin ilerleme durumunu görüntülemek için bir yükleme ekranı görünür.
    Düğümler oluşturulduktan sonra her API için Drupal düğümünün kimliği, modelin Düğüm İlişkilendirmesi sütunu altında görünür. Oluşturulan düğümü görmek için Düğüm İlişkilendirmesi sütunundaki bağlantıyı tıklayın.

API'leri Drupal düğümü olarak oluşturmak ve hemen yayınlamak için Düğüm Oluştur'u seçmek yerine Düğümleri oluştur ve yayınla'yı seçebilirsiniz.

Düğümleri yayınlama

Bir düğüm, yayınlanana kadar portal kullanıcıları tarafından görülemez. İsterseniz oluşturma işlemi sırasında düğüm yayınlamayı tercih edebilirsiniz. Düğümleri yayınlamamayı tercih ederseniz oluşturma işlemi tamamlandıktan sonra bunları manuel olarak yayınlamanız gerekir.

Bir düğümü yayınlamak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Yayınlamak istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Yayınlamak istediğiniz düzeltmeyi seçin. Yalnızca modelin tek bir düzeltmesinden düğüm yayınlayabilirsiniz.
  5. Yayınlama yöntemlerini seçin.
  6. Yayınlamak için düzeltmedeki düğümleri seçin.
  7. Güncelleme seçenekleri açılır menüsünden Düğümleri Yayınla'yı seçin.
  8. Güncelle'yi tıklayın.
  9. Düğüm İlişkilendirmesi sütunu altında düğüm kimliğini seçerek düğüme gidin.

Varsayılan olarak, yayınlanan bir API düğümünün Drupal URL'si şu biçimdedir: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. URL'nin biçimini kontrol etmek için aşağıdaki prosedürü kullanın:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde Yapılandırma > Arama ve meta veriler > URL takma adları > Kalıplar'ı seçin.
  3. Tüm SmartDokümanlar Yöntem yolları için kalıp altında yolu nasıl oluşturmak istediğinizi belirtin.
  4. Save configuration'ı (Yapılandırmayı kaydet) seçin.

Portalda önbelleğe alma işlemi nedeniyle, model sayfalarınız yayınlandıktan hemen sonra görünmeyebilir. Gerekirse aşağıdaki prosedürü kullanarak SmartDokümanlar HTML önbelleğini manuel olarak temizleyebilirsiniz:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde Yapılandırma > SmartDokümanlar'ı seçin.
  3. SmartDokümanlar model önbelleklerini yeniden oluştur'u tıklayın.

Bir düğümü yayından kaldırma

Yayınlanmış bir düğümü istediğiniz zaman yayından kaldırabilirsiniz. Bir düğümü yayından kaldırdığınızda, portal kullanıcıları o düğümü göremez.

Bir düğümü yayından kaldırmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Yayından kaldırmak istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Yayından kaldırmak istediğiniz düğümün model düzeltmesini seçin.
  5. Yayından kaldırmak üzere düzeltmedeki düğümleri seçin.
  6. Güncelleme seçenekleri açılır menüsünden Düğümleri Yayından Kaldır'ı seçin.
  7. Güncelle'yi tıklayın.

Bir modelin düzeltmesini görüntüleme

Mevcut bir modele yeni bir WADL dosyası veya OpenAPI Spesifikasyonu içe aktararak ya da manuel olarak yeni bir düzeltme oluşturarak modelin yeni bir düzeltmesini oluşturabilirsiniz. Yeni düzeltmeyi oluşturduktan sonra, düzeltmeyi oluşturup yayınlayabilirsiniz. Bu düzeltme, şu anda yayında olan Drupal düğümlerinin yerini alır.

Birden çok düzeltmeden düğümleri aynı anda oluşturabilir ve yayınlayabilirsiniz. Diğer bir deyişle, bir modelde beş düzeltmeniz varsa düzeltmelerin herhangi birinden veya tümünden düğüm yayınlayabilirsiniz. Bununla birlikte, API'nin başka bir modelde yayınlanmış düğümle aynı olan bir modelde yayınlanması API'nin eski sürümünü yayından kaldırır ve onu en son yayınlanan API'deki sürümle değiştirir.

Bir modelin düzeltmesini görmek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Görüntülemek istediğiniz model düzeltmesini seçin.
  5. Düğümleri yukarıda açıklandığı gibi oluşturun ve yayınlayın.

Düğümü düzenleme

Düğümleri oluşturduktan sonra Drupal düzenleyicisini kullanarak düzenleyebilirsiniz. Örneğin, bir API'nin HTTP fiilini ve açıklamasını düzenleyebilir ya da API'ye yeni bir sorgu veya başlık parametresi ekleyebilirsiniz. WADL dosyasından veya OpenAPI Specification'dan oluşturulan düğümleri ya da manuel olarak oluşturulan düğümleri düzenleyebilirsiniz.

Orijinal WADL dosyasını veya OpenAPI Specification'ı da düzenleyebilirsiniz. Düzenleme işlemini tamamladığınızda, WADL dosyasını veya OpenAPI Specification'ı yeni bir düzeltme olarak modele geri aktarın, ardından değişikliklerinizi yukarıda açıklanan şekilde oluşturup yayınlayın.

Drupal düzenleyicisini kullanarak bir düğümü düzenlemek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Düzenlemek istediğiniz API dokümanlarına karşılık gelen Drupal düğümüne gidin.
  3. Drupal düzenleyicisini kullanmak için Düzenle'yi seçin.
  4. Düzenlemeleriniz tamamlandıktan sonra Yöntemi Güncelle'yi seçin.

Alternatif olarak, düğümü SmartDokümanlar modelinden de düzenleyebilirsiniz:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Yayınlamak istediğiniz model düzeltmesini seçin.
  5. Düzenlemek istediğiniz yöntem için İşlemler açılır listesinden Yöntemi düzenle'yi seçin.

Bir düğümü silmek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Güncellemek istediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Yayınlamak istediğiniz model düzeltmesini seçin.
  5. Yöntemin İşlemler açılır listesinden Silme yöntemi'ni seçin.
    Dikkat: Düğümü sildiğinizde API, modelden de kaldırılır. API'nin yalnızca portal kullanıcılarından gizlenmesi için yayından kaldırılmasını istiyor ancak API'nin modelden silinmesini istemiyorsanız yukarıda açıklandığı şekilde düğümü yayından kaldırmanız gerekir.

Portalda, SmartDokümanlar modeli tarafından oluşturulan ve artık modelin geçerli yöntemlerine referans vermeyen düğümlerle ilgili bilgileri gösteren yerleşik bir rapor bulunmaktadır. Drupal menüsünden Raporlar'ı, ardından SmartDokümanlar düğüm durumu adlı raporu seçerek rapora erişin.

Bir modeli dışa ve içe aktarma

SmartDokümanlar mevcut bir modeli bir dosyaya aktarmanıza olanak tanır. Örneğin, bir üretim ve hazırlık ortamı tanımlayabilirsiniz. Daha sonra, tüm Smart Docs düzenlemelerinizi hazırlık ortamında yaparsınız. API'lerinizi yayınlamaya hazır olduğunuzda, hazırlık modelini dışa aktarır ve üretim modeline içe aktarırsınız.

Bir model içe aktarıldığında modelin yeni bir düzeltmesi oluşturulur. SmartDokümanlar, modeldeki mevcut API'leri içe aktarılan API'lerle eşleştirmeye çalışır. SmartDokümanlar bir eşleşme tespit ederse içe aktarma işlemi, mevcut API'ye karşılık gelen Drupal düğümünü günceller. SmartDokümanlar eşleşme tespit etmezse içe aktarma işlemi, API için yeni bir Drupal düğümü oluşturur.

Örneğin, 91 kimliğine sahip bir Drupal düğümüne karşılık gelen bir POST API'niz vardır. Ardından bir modeli içe aktarırsınız ve SmartDokümanlar içe aktarılan modeldeki bir POST API'nin mevcut POST API ile eşleştiğini algılar. POST API'sinde yapılan tüm güncellemeler, Drupal düğüm 91'i günceller. SmartDokümanlar eşleşme tespit etmezse yeni bir kimliğe sahip yeni bir Drupal düğümü oluşturur.

Drupal, eşleşmeyi API'nin aşağıdaki özelliklerini kullanarak gerçekleştirir:

  • internalName: Dahili model adı.
  • httpMethod: API'nin HTTP yöntemidir. Örneğin: GET, PUT, POST veya DELETE.
  • resourcePath: Kaynak yolu.
  • query params: API tarafından kullanılan tüm sorgu parametreleri.

İçe aktarılan bir API'nin dört özelliği de modeldeki mevcut bir API ile eşleşirse SmartDokümanlar mevcut Drupal düğümünü günceller.

Dışa aktarılan model, kaynak ve yöntem girişlerine sahip tek bir JSON nesnesiyle temsil edilir. Bu sayede, dışa aktarılan modeli bir kaynağı veya yöntemi değiştirmek üzere düzenleyebilir ve daha sonra modeli yeniden içe aktarabilirsiniz. JSON nesnesini düzenlerseniz şu alanları değiştirmeyin:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Bir modeli dışa aktarmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Dışa aktarmak istediğiniz model için İşlemler bölümünde Dışa aktar'ı seçin.
  4. Dışa aktarma dosyası türünü SmartDokümanlar JSON olarak seçin.
  5. Dışa aktar'ı tıklayın.
  6. Dosyayı diske kaydetmeniz veya bir düzenleyicide açmanız istenir.

Bir modeli içe aktarmak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. İçe aktarmak istediğiniz model için İşlemler bölümünde İçe aktar'ı seçin.
  4. Biçim Seçin açılır listesinden SmartDokümanlar JSON seçeneğini belirleyin.
  5. Yükleme Türü'nde Dosya veya URL'yi seçin:
    1. Dosya'yı seçerseniz JSON dosyasına gidin.
    2. URL'yi seçerseniz SmartDokümanlar JSON dosyasının URL'sini belirtin.
  6. Öğeyi modele aktarmak için İçe aktar'ı tıklayın.
  7. Artık modeli oluşturabileceğiniz model bilgi sayfasına yönlendirilirsiniz. İçe aktarma işleminin modelin yeni bir düzeltmesini oluşturacağını unutmayın.
  8. Düğümleri oluşturun ve yayınlayın.

SmartDokümanlar şablonunu düzenleme

SmartDokümanlar şablonu Drupal düğümlerinizin ekranda nasıl görüneceğini tanımlar. Her SmartDokümanlar modeli aynı varsayılan şablonu kullanabilir veya tek bir model için kullanılan şablonu manuel olarak özelleştirebilirsiniz.

SmartDokümanlar şablonu, Sahne .hbr dosyası, CSS dosyaları ve JavaScript dosyaları olarak kodlanmış bir şablon dosyası içerir. Gidonlarla içeriğin büyük bir kısmı, &123;&123;body}} gibi yerleşik tutma çubuğu ifadeleri kullanılarak değişken odaklı olur. Mevcut Gidon ifadelerinin listesi dosyanın üst kısmındaki bir açıklamada sağlanır. Şablonlarınızı özelleştirmek için Gidonları kullanma hakkında bilgi edinmek için http://handlebarsjs.com adresine bakın.

Aşağıdaki bölümlerde, tüm yeni modellerde kullanılmak üzere veya yeni API'leri mevcut bir modele aktarırken özel bir SmartDokümanlar şablon dosyasının nasıl yükleneceği, varsayılan orijinal SmartDokümanlar şablon dosyasının nasıl geri yükleneceği ve tek bir model için SmartDokümanlar şablonunun nasıl değiştirileceği açıklanmaktadır.

Özel bir SmartDokümanlar şablon dosyası yükleme

Özel bir SmartDokümanlar şablon dosyasını, yeni modeller oluştururken veya yeni API'leri mevcut bir modele aktarırken varsayılan şablon olarak kullanmak üzere Handlebars .hbr dosyası olarak yükleyebilirsiniz.

Özel SmartDokümanlar şablon dosyanızı oluştururken başlangıç noktası olarak varsayılan SmartDokümanlar şablon dosyasını kullanmak isterseniz aşağıdaki adresten bir kopya indirebilirsiniz: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Özel bir SmartDokümanlar şablon dosyası yüklemek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde Yapılandırma > SmartDokümanlar'ı seçin.
  3. Sayfanın Gelişmiş Ayarlar alanını genişletin.
  4. Özelleştirilmiş yöntem şablonu yükleyin bölümünde Dosya Seç'i tıklayın ve Handlebars .hbr dosyasına gidin.
  5. Yükle'yi tıklayın.
  6. Save configuration'ı (Yapılandırmayı kaydet) tıklayın.

Varsayılan SmartDokümanlar şablon dosyasını geri yükleme

Varsayılan SmartDokümanlar şablon dosyasını geri yükleyebilirsiniz. Geri yüklendikten sonra, yeni model oluştururken veya yeni API'leri mevcut bir modele aktarırken varsayılan SmartDokümanlar şablon dosyası kullanılır.

Varsayılan SmartDokümanlar şablon dosyasını geri yüklemek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde Yapılandırma > SmartDokümanlar'ı seçin.
  3. Sayfanın Gelişmiş Ayarlar alanını genişletin.
  4. Özelleştirilmiş yöntem şablonu yükleyin bölümünde, özel SmartDokümanlar şablon dosyasının yanındaki Kaldır'ı tıklayın.
  5. Save configuration'ı (Yapılandırmayı kaydet) tıklayın.

SmartDokümanlar şablonunu tek bir model için değiştirme

Tek bir model için kullanılan şablonu değiştirebilirsiniz.

Tek bir modelin şablonunu değiştirmek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. Düzenlemek istediğiniz model için İşlemler bölümünde Ayarlar'ı seçin.
  4. Yöntem Şablonu alanında, şablonu gerektiği gibi düzenleyin.
  5. Şablonu kaydet'i tıklayın.
  6. Drupal düğümüne gidin. Şablonunuzdaki değişiklikleri sayfada göreceksiniz.

SmartDokümanlar kimlik doğrulama türünü yapılandırma

SmartDokümanlar'da tanımlanan API'ler açık olabilir. Yani, bu API'lere erişmek için kimlik doğrulama bilgisi gerekmez veya API'ler güvenli olabilir. Güvenli bir API, API'ye çağrı yaparken kimlik bilgilerini iletmenizi gerektirir.

SmartDokümanlar güvenli bir API için aşağıdaki kimlik doğrulama türlerini destekler:

  • Temel kimlik doğrulama - Kullanıcı adı ve şifre çifti olarak temel kimlik doğrulama bilgilerini iletin. Kimlik bilgisi türü olarak OAuth'un kullanılmasını belirtmezseniz API varsayılan olarak temel kimlik doğrulamasını kullanır.
  • OAuth 2.0: Üçüncü taraf servis sağlayıcı, kullanıcının kimlik bilgilerini doğrular, kullanıcının API yetkilendirmesi almasını sağlar ve ardından bir erişim jetonu yayınlar. Korunan bir API'ye SmartDokümanlar isteğinde bulunduğunuzda SmartDokümanlar isteği oluşturur ve servis sağlayıcıya gönderir. Daha sonra servis sağlayıcı, jetonu doğrular ve süresinin dolmadığından emin olur.
  • Özel jeton: Her isteğe başlık veya sorgu parametresi olarak bir jeton değeri iletin.

Her kimlik doğrulama türü için kimlik doğrulamanın özelliklerini tanımlayan bir güvenlik şeması oluşturursunuz. Örneğin, özel jeton kimlik doğrulamasında güvenlik şeması, jetonun nasıl iletildiğini (başlık, sorgu parametresi, gövde parametresi) ve jetonun adını tanımlar.

Güvenlik şeması, bir modelin belirli bir düzeltmesiyle ilişkilendirilir. Bu nedenle, bir modelin yeni bir düzeltmesini oluşturursanız bu düzeltme için güvenlik şemalarını yeniden tanımlamanız gerekir.

Bir WADL dosyasında, bir API'nin kimlik doğrulama gerektirip gerektirmediğini aşağıda gösterildiği gibi <apigee:authentication> Apigee etiketini kullanarak belirtirsiniz:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

API açıksa required özelliğini false olarak ayarlayın.

WADL dosyasında kimlik doğrulama türünü belirtemeyeceğinizi unutmayın. Bu işlemi, düğümü Drupal'da düzenleyerek yapabilirsiniz. WADL dosyaları hakkında daha fazla bilgi için WADL Referansı'na bakın.

SmartDokümanlar, Drupal'daki API sayfasına kullanıcıların temel kimlik doğrulama bilgilerini belirtebilmesi için aşağıdaki düğmeyi ekler:

Düğümü kimlik doğrulama türünü OAuth olarak ayarlayacak şekilde düzenlerseniz SmartDokümanlar sayfaya aşağıdaki düğmeyi ekler:

SmartDokümanlar özel jeton için şunları ekler:

Temel kimlik doğrulamasını yapılandırma

API'nizle temel kimlik doğrulamasını kullanıyorsanız modeli oluşturmak için kullandığınız WADL dosyasında yalnızca <apigee:authentication> etiketini belirtmeniz gerekir.

WADL dosyası dışında bir kaynaktan oluşturulan yöntemlere temel kimlik doğrulaması uygulamak için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. İstediğiniz model için İşlemler bölümünden API Düzeltmeleri'ni seçin.
  4. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Güvenlik Ayarları'nı seçin.
  5. Güvenlik Şeması Ekle'yi seçin.
  6. Güvenlik şemasının adını belirtin.
  7. Tür olarak Temel'i seçin.
  8. Gönder'i seçin.
  9. Modeldeki her yöntemin Güvenlik Şeması'nı temel şemanıza göre ayarlamak için yöntemi düzenleyin.
    1. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
    2. İstediğiniz model için İşlemler bölümünden API Düzeltmeleri'ni seçin.
    3. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Düzeltme Ayrıntıları'nı seçin.
    4. Düzenlemek istediğiniz API için Yöntemi Düzenle'yi seçin.
    5. API için Güvenlik Şeması'nı seçin.
    6. API'yi kaydedin.

OAuth 2.0 kimlik doğrulamasını yapılandırma

SmartDokümanlar'da temel kimlik doğrulama yerine varsayılan kimlik doğrulama yerine OAuth 2.0'ı kullanacak şekilde bir model yapılandırabilirsiniz. OAuth'u iki konumda yapılandırırsınız:

  1. Düzeltmeyle ilgili Güvenlik Ayarları altında, bir modelin her düzeltmesi için bir güvenlik şeması oluşturun.
  2. Modelin Ayarlar bölümünde, modelin tüm düzeltmeleri için İstemci Kimliği'ni ve İstemci Sırrı'nı belirtin.

OAuth'u etkinleştirmek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. İstediğiniz model için İşlemler bölümünde API Düzeltmeleri'ni seçin.
  4. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Güvenlik Ayarları'nı seçin.
  5. Güvenlik Şeması Ekle'yi seçin.
  6. Güvenlik şemasının adını belirtin.
  7. Type (Tür) olarak OAuth 2.0'ı seçin.
  8. İzin Türü'nü ayarlayın.
  9. Değerleri Yetkilendirme URL'si alanlarına girin. Yetkilendirme URL'si erişim jetonunu almak için kullanılır.
  10. Yetkilendirme fiili'ni GET veya POST olarak ayarlayın.
  11. Access Token URL (Erişim Jetonu URL'si) değerini girin. Erişim Jetonu URL'si, istek jetonunu bir erişim jetonuyla değiştirmek için kullanılan URL'dir.
  12. Access Token parametre adı girin.
  13. Jetonu nasıl ileteceğinizi belirtmek için In'i kullanın: Header, Query veya Body.
  14. OAuth Kapsamları'nı ayarlayın.
  15. Gönder'i seçin.
  16. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  17. Model için İşlemler açılır menüsünden Ayarlar'ı seçin.
  18. Değerleri Client-ID (İstemci Kimliği) ve Client Secret (İstemci Gizli Anahtarı) alanlarına girin.
  19. Şablon kimlik doğrulama ayarlarını kaydet'i seçin.
  20. Modeldeki her yöntemin Güvenlik Şeması için OAuth güvenlik şemanızı ayarlama yöntemini düzenleyin.
    1. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
    2. İstediğiniz model için İşlemler bölümünden API Düzeltmeleri'ni seçin.
    3. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Düzeltme Ayrıntıları'nı seçin.
    4. Düzenlemek istediğiniz API için Yöntemi Düzenle'yi seçin.
    5. API için Güvenlik Şeması'nı seçin.
    6. API'yi kaydedin.

Özel jeton kimlik doğrulamasını yapılandırma

Bir modeli, özel jeton kimlik doğrulamasını kullanacak şekilde yapılandırabilirsiniz.

Özel jetonları etkinleştirmek için:

  1. Portalınıza yönetici veya içerik oluşturma ayrıcalıklarına sahip bir kullanıcı olarak giriş yapın.
  2. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
  3. İstediğiniz model için İşlemler bölümünden API Düzeltmeleri'ni seçin.
  4. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Güvenlik Ayarları'nı seçin.
  5. Güvenlik Şeması Ekle'yi seçin.
  6. Güvenlik şemasının adını belirtin.
  7. Tür olarak Apikey'i seçin.
  8. Jetonu içeren Param Adı'nı belirleyin.
  9. Jetonu nasıl ileteceğinizi belirtmek için In'i kullanın: Header, Query veya Body.
  10. Gönder'i seçin.
  11. Modeldeki her yöntemin Güvenlik Şeması'nı jeton şemanıza ayarlayacak şekilde yöntemi düzenleyin.
    1. Drupal yönetim menüsünde İçerik > SmartDokümanlar'ı seçin.
    2. İstediğiniz model için İşlemler bölümünden API Düzeltmeleri'ni seçin.
    3. Düzenlemek istediğiniz model düzeltmesi için İşlemler'in altında Düzeltme Ayrıntıları'nı seçin.
    4. Düzenlemek istediğiniz API için Yöntemi Düzenle'yi seçin.
    5. API için Güvenlik Şeması'nı seçin.
    6. API'yi kaydedin.

Model silme

Bir modeli sildiğinizde (İçerik > SmartDokümanlar, Drupal'daki İşlemler alanında Sil) model, Edge kuruluşunuzdan silinir. Bu, diğer portalların modele referans verdiği durumlarda modelin artık kullanılamayacağı anlamına gelir. Daha fazla bilgi için SmartDoc modelleri ve şablonları hakkında bölümüne bakın.