Memublikasikan API menggunakan Edge API

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Bagian ini menjelaskan cara menggunakan Edge API guna membuat produk API untuk dipublikasikan di portal developer.

Membuat produk API menggunakan API

Produk API memungkinkan developer untuk mendaftar aplikasi yang menggunakan API menggunakan kunci API dan token akses OAuth. Produk API dirancang untuk memungkinkan Anda untuk 'memaketkan' resource API lalu memublikasikan paket tersebut ke berbagai grup developer. Misalnya, Anda mungkin perlu memublikasikan satu set resource API ke partner developer, sementara Anda memublikasikan paket lain untuk developer eksternal. Produk API memungkinkan Anda untuk Anda dapat melakukan pemaketan ini dengan cepat, tanpa memerlukan perubahan pada API Anda sendiri. Channel manfaat tambahan adalah akses developer dapat 'diupgrade' dan 'didowngrade' tanpa memerlukan pengembang untuk memperoleh kunci konsumen baru untuk aplikasi mereka.

Untuk membuat produk API menggunakan API, keluarkan permintaan POST ke /organizations/{org_name}/apiproducts. Untuk informasi selengkapnya, lihat referensi API Membuat Produk API.

Permintaan berikut membuat produk API bernama weather_free. Produk API menyediakan akses ke semua API yang diekspos oleh proxy API bernama weatherapi yang yang di-deploy di lingkungan test. Jenis persetujuan ditetapkan ke auto yang menunjukkan bahwa permintaan akses akan disetujui.

curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
-u email:password 

Contoh respons:

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

Produk API yang dibuat di atas menerapkan skenario paling dasar, yaitu mengizinkan permintaan ke Proxy API dalam lingkungan. Class tersebut mendefinisikan produk API yang memungkinkan aplikasi yang diotorisasi untuk mengakses sumber daya API apa pun yang diakses melalui proxy API yang berjalan di lingkungan pengujian. Produk API menampilkan setelan konfigurasi tambahan yang memungkinkan Anda menyesuaikan kontrol akses ke API untuk berbagai grup developer. Misalnya, Anda dapat membuat dua produk API yang memberikan akses ke proxy API yang berbeda. Anda juga dapat membuat dua produk API yang memberikan akses ke Proxy API, tetapi dengan setelan Kuota terkait yang berbeda.

Setelan konfigurasi produk API

Produk API menampilkan opsi konfigurasi berikut:

Nama Deskripsi Default Wajib?
apiResources

Daftar URI yang dipisahkan koma, atau jalur resource, 'bundled' ke dalam API Google.

Secara default, jalur resource dipetakan dari proxy.pathsuffix variabel. Akhiran jalur proxy didefinisikan sebagai fragmen URI yang mengikuti Jalur dasar ProxyEndpoint. Misalnya, dalam contoh produk API di bawah ini, Elemen apiResources ditetapkan sebagai /forecastrss. Karena Jalur Dasar yang ditentukan untuk proxy API ini adalah /weather, yang berarti hanya permintaan ke /weather/forecastrss diizinkan oleh produk API ini.

Anda dapat memilih jalur tertentu, atau memilih semua subjalur dengan karakter pengganti. Karakter pengganti (/** dan /*) didukung. Karakter pengganti tanda bintang ganda menunjukkan bahwa semua sub-URI akan disertakan. Satu tanda bintang menunjukkan bahwa hanya URI satu tingkat di bawah yang disertakan.

Secara default, '/' mendukung resource yang sama dengan '/**' serta Base Jalur yang ditentukan oleh proxy API. Misalnya, jika Jalur Dasar proxy API adalah /v1/weatherapikey, lalu produk API mendukung permintaan ke /v1/weatherapikey dan ke semua sub-URI, seperti /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, dan seterusnya. Lihat Mengelola produk API untuk informasi tentang cara mengubah perilaku {i>default<i} ini.

T/A Tidak
approvalType Menentukan bagaimana kunci API disetujui untuk mengakses API yang ditetapkan oleh produk API. Jika disetel ke manual, kunci yang dibuat untuk aplikasi berada dalam status 'pending' status. Kunci tersebut tidak akan berfungsi sebelum disetujui secara eksplisit. Jika ditetapkan ke auto, semua kunci dibuat di folder 'disetujui' dan langsung bekerja. (auto adalah yang biasanya digunakan untuk memberikan akses ke produk API gratis/uji coba yang menyediakan Kuota terbatas atau kemampuan lainnya.) T/A Ya
attributes

Array atribut yang dapat digunakan untuk memperluas profil produk API default dengan {i>metadata<i} khusus pelanggan.

Gunakan properti ini untuk menentukan tingkat akses produk API baik sebagai public, private, atau internal. Contoh:
"attributes": [
{
"name": "akses",
"value": "public"
},
{
"name": "foo",
"value": "foo"
},
{
"name": "bar",
"value": "bar"
}
]
T/A Tidak
scopes Daftar cakupan OAuth yang dipisahkan koma yang divalidasi saat runtime. (Apigee Edge memvalidasi bahwa cakupan dalam token akses yang ditampilkan cocok dengan cakupan yang ditetapkan di API product.) T/A Tidak
proxies Proxy API bernama yang terikat dengan produk API ini. Dengan menentukan {i>proxy<i}, Anda dapat mengaitkan resource di produk API dengan proxy API tertentu, sehingga mencegah developer agar tidak mengakses resource tersebut melalui proxy API lainnya. T/A Tidak. Jika tidak ditentukan, apiResources harus ditentukan secara eksplisit (lihat info untuk apiResources di atas), dan variabel flow.resource.name ditetapkan di Kebijakan TetapkanMessage.
environments Lingkungan yang diberi nama (misalnya, 'test' atau 'prod") yang menjadi tempat terikat produk API ini. Dengan menentukan satu atau beberapa lingkungan, Anda dapat mengikat resource yang tercantum dalam produk API ke lingkungan tertentu, sehingga mencegah developer mengakses resource tersebut melalui API {i>proxy<i} di lingkungan lain. Setelan ini digunakan, misalnya, untuk mencegah resource yang terkait dengan proxy API di 'prod' agar tidak diakses oleh proxy API yang di-deploy di 'test'. T/A Tidak. Jika tidak ditentukan, apiResources harus ditentukan secara eksplisit, dan Variabel flow.resource.name ditetapkan dalam kebijakan MenetapkanMessage.
quota Jumlah permintaan yang diizinkan per aplikasi selama interval waktu yang ditentukan. T/A Tidak
quotaInterval Jumlah unit waktu yang digunakan untuk mengevaluasi kuota T/A Tidak
quotaTimeUnit Unit waktu (menit, jam, hari, atau bulan) yang digunakan untuk menghitung kuota. T/A Tidak

Berikut ini memberikan contoh yang lebih mendetail untuk membuat produk API.

curl -X POST  https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
  "apiResources": [ "/forecastrss" ],
  "approvalType": "auto", 
  "attributes":
    [ {"name": "access", "value": "public"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u email:password

Contoh Respons

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "access",
    "value" : "public"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

Tentang cakupan

Cakupan adalah konsep yang digambar dari OAuth dan memetakan secara kasar ke konsep 'izin'. Aktif Apigee Edge, cakupannya sepenuhnya bersifat opsional. Anda dapat menggunakan cakupan untuk mencapai otorisasi. Setiap kunci konsumen yang dikeluarkan untuk aplikasi dikaitkan dengan 'cakupan master'. Tujuan cakupan master adalah kumpulan semua cakupan di seluruh produk API untuk aplikasi ini yang telah disetujui. Sebagai aplikasi yang disetujui untuk menggunakan beberapa produk API, cakupan master adalah gabungan dari semua cakupan yang ditetapkan dalam produk API dengan kunci konsumen yang telah disetujui.

Lihat produk API

Untuk melihat produk API yang dibuat untuk organisasi menggunakan API, lihat bagian berikut:

Berikut ini contoh cara melihat produk API menggunakan API:

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

Respons akan terlihat seperti ini (hanya sebagian respons yang ditampilkan):

{
  "product" : [ {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "payment api product",
    "displayName" : "payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  }, {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "messaging api product",
    "displayName" : "messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  } ],
  "totalRecords" : 2
}

Mendaftarkan developer menggunakan API

Semua aplikasi adalah milik developer atau perusahaan. Oleh karena itu, untuk membuat aplikasi, Anda harus terlebih dahulu untuk mendaftarkan pengembang atau perusahaan.

Developer terdaftar dalam organisasi dengan membuat profil. Perhatikan bahwa developer yang disertakan di profil digunakan sebagai kunci unik bagi developer di seluruh Apigee Edge.

Untuk mendukung monetisasi, Anda harus menentukan monetisasi saat membuat atau mengedit developer. Anda juga dapat menentukan untuk digunakan dalam analisis kustom, penerapan kebijakan kustom, dan sebagainya; perintah acak ini atribut ini tidak akan ditafsirkan oleh Apigee Edge,

Misalnya, permintaan berikut mendaftarkan profil untuk developer yang memiliki alamat email ntesla@theremin.com dan menentukan subset monetisasi menggunakan API Create developer:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ 
  { 
    "name" : "project_type", 
    "value" : "public"
  },
  {    
   "name": "MINT_BILLING_TYPE",
   "value": "POSTPAID"
  },
  {
   "name": "MINT_DEVELOPER_ADDRESS",
   "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
  },
  {
   "name": "MINT_DEVELOPER_TYPE",
   "value": "TRUSTED"
  },
  {    
   "name": "MINT_HAS_SELF_BILLING,
   "value": "FALSE"
  },
  {
   "name" : "MINT_SUPPORTED_CURRENCY",
   "value" : "usd"
  }
 ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password 

Contoh Respons

{
          "email" : "ntesla@theremin.com",
          "firstName" : "Nikola",
          "lastName" : "Tesla",
          "userName" : "theremin",
          "organizationName" : "{org_name}",
          "status" : "active",
          "attributes" : [ 
          {
            "name" : "project_type",
            "value" : "public"
          },
          {    
             "name": "MINT_BILLING_TYPE",
             "value": "POSTPAID"
          },
          {
             "name": "MINT_DEVELOPER_ADDRESS",
             "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
          },
          {
             "name": "MINT_DEVELOPER_TYPE",
             "value": "TRUSTED"
          },
          {    
             "name": "MINT_HAS_SELF_BILLING,
             "value": "FALSE"
          },
          {
             "name" : "MINT_SUPPORTED_CURRENCY",
             "value" : "usd"
          } 
          ],
          "createdAt" : 1343189787717,
          "createdBy" : "admin@apigee.com",
          "lastModifiedAt" : 1343189787717,
          "lastModifiedBy" : "admin@apigee.com"
        }

Mendaftarkan aplikasi developer menggunakan API

Setiap aplikasi yang terdaftar di Apigee Edge akan dikaitkan dengan developer dan produk API. Saat aplikasi didaftarkan atas nama developer, Apigee Edge membuat "kredensial" (sebuah pasangan kunci dan rahasia pengguna) yang mengidentifikasi aplikasi. Aplikasi kemudian harus meneruskan kredensial ini sebagai bagian dari setiap permintaan ke produk API yang terkait dengan aplikasi.

Permintaan berikut menggunakan Opsi Buat Developer App API untuk mendaftarkan aplikasi bagi developer yang Anda buat di atas: ntesla@theremin.com. Saat mendaftarkan aplikasi, Anda menentukan nama untuk aplikasi tersebut, callbackUrl, dan daftar satu atau beberapa API produk:
$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "keyExpiresIn" : "2630000000",
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password 

callbackUrl digunakan oleh beberapa jenis pemberian OAuth (seperti kode otorisasi) untuk memvalidasi permintaan pengalihan dari aplikasi. Jika Anda menggunakan OAuth, nilai ini harus ditetapkan ke nilai yang sama dengan redirect_uri yang digunakan untuk membuat permintaan OAuth.

Atribut keyExpiresIn menentukan, dalam milidetik, selama masa aktif kunci konsumen yang akan dibuat untuk aplikasi developer. Nilai {i>default<i}, -1, menunjukkan masa berlaku tanpa batas.

Contoh Respons

{
  "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
  "attributes": [
    {
      "name": "DisplayName",
      "value": "Test Key Expires"
    },
    {
      "name": "Notes",
      "value": "Just testing this attribute"
    }
  ],
  "createdAt": 1421770824390,
  "createdBy": "wwitman@apigee.com",
  "credentials": [
    {
      "apiProducts": [
        {
          "apiproduct": "ProductNoResources",
          "status": "approved"
        }
      ],
      "attributes": [],
      "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
      "consumerSecret": "AX7lGGIRJs6s8J8y",
      "expiresAt": 1424400824401,
      "issuedAt": 1421770824401,
      "scopes": [],
      "status": "approved"
    }
  ],
  "developerId": "e4Oy8ddTo3p1BFhs",
  "lastModifiedAt": 1421770824390,
  "lastModifiedBy": "wwitman@apigee.com",
  "name": "TestKeyExpires",
  "scopes": [],
  "status": "approved"
}

Mengelola kunci konsumen untuk aplikasi menggunakan API

Mendapatkan kunci konsumen (Kunci API) untuk aplikasi

Kredensial untuk aplikasi (produk API, kunci konsumen, dan rahasia) ditampilkan sebagai bagian dari profil aplikasi Anda. Administrator organisasi dapat mengambil kunci konsumen kapan saja.

Profil aplikasi menampilkan nilai kunci dan rahasia konsumen, serta status konsumen kunci, serta semua pengaitan produk API untuk kunci tersebut. Sebagai admin, Anda dapat mengambil profil kunci konsumen kapan saja menggunakan Mendapatkan Detail Kunci untuk Aplikasi Developer API:

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Contoh Respons

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Lihat Dapatkan Detail Kunci untuk Aplikasi Developer untuk informasi selengkapnya.

Menambahkan produk API ke aplikasi dan kunci

Untuk mengupdate aplikasi agar menambahkan produk API baru, Anda sebenarnya menambahkan produk API ke kunci aplikasi menggunakan Add API Product to Key API. Lihat Tambahkan Produk API ke Kunci untuk mengetahui informasi selengkapnya.

Menambahkan produk API ke kunci aplikasi memungkinkan aplikasi yang memiliki kunci untuk mengakses API resource yang dipaketkan dalam produk API. Panggilan metode berikut menambahkan produk API baru ke aplikasi:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password 

Contoh Respons:

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Setujui kunci konsumen

Dengan menetapkan jenis persetujuan ke manual, Anda dapat mengontrol developer dapat mengakses resource yang dilindungi oleh produk API. Saat produk API memiliki kunci persetujuan ditetapkan ke manual, kunci konsumen harus disetujui secara eksplisit. Kunci dapat berupa secara eksplisit disetujui menggunakan Setujui atau Cabut Kunci tertentu Aplikasi Developer API:

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password

Contoh Respons

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Lihat Setujui atau Cabut Kunci Aplikasi Developer Tertentu untuk mendapatkan izin lainnya.

Menyetujui produk API untuk kunci pengguna

Pengaitan produk API dengan kunci konsumen juga memiliki status. Agar akses API menjadi berhasil, kunci konsumen harus disetujui, dan kunci konsumen harus disetujui untuk produk API yang sesuai. Pengaitan kunci konsumen dengan produk API dapat disetujui dengan menggunakan Setujui atau Cabut Produk API untuk Kunci untuk Pengembang API Aplikasi:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password

Perintah cURL ini tidak menampilkan respons. Lihat Setujui atau Cabut Produk API untuk Kunci Aplikasi Developer guna mendapatkan izin lainnya.

Cabut produk API untuk kunci konsumen

Ada banyak alasan mengapa Anda mungkin perlu mencabut pengaitan kunci konsumen dengan API Google. Anda mungkin perlu menghapus produk API dari kunci konsumen karena pembayaran belum dilakukan oleh developer, masa uji coba yang telah habis masa berlakunya, atau Saat aplikasi dipromosikan dari satu produk API ke lain.

Untuk mencabut pengaitan kunci konsumen dengan produk API, gunakan elemen Setujui atau Cabut Kunci Aplikasi Developer API Tertentu, menggunakan tindakan yang dicabut terhadap kunci konsumen aplikasi pengembangan:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password

Perintah cURL ini tidak menampilkan respons. Lihat Setujui atau Cabut Kunci Aplikasi Developer Tertentu untuk mendapatkan izin lainnya.

Terapkan setelan produk API

Agar produk API dapat diterapkan, salah satu jenis kebijakan berikut harus disertakan ke API alur proxy:

  • VerifyAPIKey: Mengambil referensi ke kunci API, memverifikasi bahwa kunci tersebut mewakili aplikasi yang valid, dan cocok dengan produk API. Lihat Memverifikasi kebijakan Kunci API untuk banyak lagi.
  • OAuthV1, operasi “VerifyAccessToken”: Memverifikasi tanda tangan, memvalidasi Token akses dan “kunci konsumen” OAuth 1.0a, serta mencocokkan aplikasi dengan produk API. Lihat kebijakan OAuth v1.0a untuk banyak lagi.
  • OAuthV2, operasi “VerifyAccessToken”: Memverifikasi bahwa akses OAuth 2.0 token valid, mencocokkan token dengan aplikasi, memverifikasi bahwa aplikasi valid, lalu cocok aplikasi ke produk API. Lihat OAuth beranda untuk melihat lebih banyak.

Setelah kebijakan dan produk API dikonfigurasi, proses berikut akan dijalankan oleh Apigee Tepi:

  1. Permintaan diterima oleh Apigee Edge dan diarahkan ke proxy API yang sesuai.
  2. Kebijakan dijalankan yang memverifikasi kunci API atau token akses OAuth yang diberikan oleh dengan klien besar.
  3. Edge me-resolve Kunci API atau token akses ke profil aplikasi.
  4. Edge menyelesaikan daftar (jika ada) produk API yang terkait dengan aplikasi.
  5. Produk API pertama yang cocok akan digunakan untuk mengisi variabel Kuota.
  6. Jika tidak ada produk API yang cocok dengan kunci API atau token akses, permintaan akan ditolak.
  7. Edge menerapkan kontrol akses berbasis URI (lingkungan, proxy API, dan jalur URI) berdasarkan Setelan produk API, beserta setelan Kuota.