פרסום ממשקי API באמצעות ממשק ה-API של Edge

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

בקטע הזה מוסבר איך להשתמש ב-Edge API כדי ליצור מוצרי API לפרסום בפורטלי מפתחים.

יצירת מוצרי API באמצעות API

מוצרי API מאפשרים למפתחים לרשום אפליקציות שצורכות ממשקי API באמצעות מפתחות API ואסימוני גישה מסוג OAuth. מוצרי API נועדו לאפשר לכם 'לארוז' משאבי API ואז לפרסם את החבילות האלה לקבוצות שונות של מפתחים. לדוגמה, יכול להיות שתצטרכו לפרסם קבוצה אחת של משאבי API למפתחים של השותף, וקבוצה אחרת של משאבי API למפתחים חיצוניים. מוצרי API מאפשרים לכם לבצע את הצירוף הזה תוך כדי תנועה, בלי שתצטרכו לבצע שינויים בממשקי ה-API עצמם. היתרון הנוסף הוא שאפשר לשדרג או לשנמך את הגישה של המפתחים בלי שהם יצטרכו לקבל מפתחות צרכן חדשים לאפליקציות שלהם.

כדי ליצור מוצר API באמצעות ה-API, שולחים בקשת POST אל /organizations/{org_name}/apiproducts. מידע נוסף מופיע במאמרי העזרה של ה-API בנושא יצירת מוצר API.

הבקשה הבאה יוצרת מוצר API בשם weather_free. מוצר ה-API מספק גישה לכל ממשקי ה-API שנחשפים על ידי proxy ל-API שנקרא weatherapi, שפריסתו מתבצעת בסביבת test. סוג האישור מוגדר כ-auto, כלומר כל בקשה לגישה תאושר.

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 

דוגמה לתשובה:

{
  "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" : [ ]
}

מוצר ה-API שנוצר למעלה מיישם את התרחיש הבסיסי ביותר, שבו מאשרים בקשות ל-proxy ל-API בסביבה. הוא מגדיר מוצר API שמאפשר לאפליקציה מורשית לגשת לכל משאבי ה-API שאליהם ניגשים דרך שרת ה-proxy ל-API שפועל בסביבת הבדיקה. מוצרי API חושפים הגדרות נוספות שמאפשרות לכם להתאים אישית את בקרת הגישה לממשקי ה-API עבור קבוצות שונות של מפתחים. לדוגמה, אפשר ליצור שני מוצרי API שנותנים גישה לשרתי proxy שונים ל-API. אפשר גם ליצור שני מוצרי API שנותנים גישה לאותם שרתי proxy ל-API, אבל עם הגדרות שונות של מכסת שימוש.

הגדרות התצורה של מוצר API

מוצרי API חושפים את אפשרויות ההגדרה הבאות:

בדוגמה הבאה מוסבר בפירוט איך ליצור מוצר 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

דוגמה לתשובה

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

מידע על היקפים

היקף הוא מושג שמוגדר ב-OAuth, והוא מקביל בערך למושג 'הרשאה'. ב-Apigee Edge, היקפי הגישה הם אופציונליים לחלוטין. אפשר להשתמש בהיקפים כדי להשיג הרשאה עם רמת פירוט גבוהה יותר. כל טוקן צרכן שמונפק לאפליקציה משויך ל 'היקף ראשי'. ההיקף הראשי הוא קבוצת כל ההיקפים בכל מוצרי ה-API שהאפליקציה אושרה לשימוש בהם. באפליקציות שאושרו לשימוש בכמה מוצרי API, היקף ההרשאות הראשי הוא איחוד של כל היקפי ההרשאות שהוגדרו במוצרי ה-API שאושרו לשימוש בטוקן הצרכן.

הצגת מוצרי API

כדי לראות את מוצרי ה-API שנוצרו לארגון באמצעות ה-API, אפשר לעיין בקטעים הבאים:

• הצגת מוצרי API (עם מונטיזציה)

  כברירת מחדל, מוצגים רק מוצרי API שמניבים הכנסות (כלומר, מוצרי API עם לפחות מודל חיוב אחד שפורסם). כדי להציג את כל מוצרי ה-API, מגדירים את פרמטר השאילתה monetized לערך false. זה שווה ערך להנפקת בקשת GET ל-API של מוצרים שאינם מניבים הכנסות: https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true

• הצגת מוצרי API (לא מניבים הכנסות)
• הצגת מוצרי API שעומדים בדרישות למפתחים
• הצגת מוצרי API שעומדים בדרישות של חברה

בדוגמה הבאה מוצג איך אפשר לראות מוצרי API באמצעות ה-API:

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

התשובה אמורה להיראות כך (מוצג רק חלק מהתשובה):

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

הרשמת מפתחים באמצעות ה-API

כל האפליקציות שייכות למפתחים או לחברות. לכן, כדי ליצור אפליקציה, קודם צריך לרשום מפתח או חברה.

מפתחים נרשמים בארגון על ידי יצירת פרופיל. שימו לב שכתובת האימייל של המפתח שמופיעה בפרופיל משמשת כמפתח הייחודי של המפתח ב-Apigee Edge.

כדי לתמוך במונטיזציה, צריך להגדיר את מאפייני המונטיזציה כשיוצרים או עורכים מפתחים. אפשר גם להגדיר מאפיינים שרירותיים אחרים לשימוש בניתוח נתונים מותאם אישית, באכיפת מדיניות מותאמת אישית וכו'. מאפיינים שרירותיים כאלה לא יפורשו על ידי Apigee Edge,

לדוגמה, הבקשה הבאה רושמת פרופיל למפתח שכתובת האימייל שלו היא ntesla@theremin.com ומגדירה קבוצת משנה של מאפייני מונטיזציה באמצעות Create developer API:

$ 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 

דוגמה לתשובה

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

רישום אפליקציות למפתחים באמצעות ה-API

כל אפליקציה שרשומה ב-Apigee Edge משויכת למפתח ולמוצר API. כשרושמים אפליקציה בשם מפתח, Apigee Edge יוצר 'פרטי כניסה' (זוג של מפתח צרכן וסוד) שמזהים את האפליקציה. לאחר מכן, האפליקציה צריכה להעביר את פרטי הכניסה האלה כחלק מכל בקשה למוצר API שמשויך לאפליקציה.

$ 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 משמש חלק מסוגי מענקי OAuth (כמו קוד הרשאה) כדי לאמת בקשות להפניה אוטומטית מהאפליקציה. אם משתמשים ב-OAuth, הערך הזה צריך להיות זהה לערך של redirect_uri שמשמש לשליחת בקשות OAuth.

במאפיין keyExpiresIn מציינים את משך הזמן, באלפיות השנייה, שבו טוקן הצרכן שייווצר לאפליקציית המפתח יהיה תקף. ערך ברירת המחדל, ‎-1, מציין תקופת תוקף אינסופית.

דוגמה לתשובה

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

ניהול מפתחות צרכן לאפליקציות באמצעות ה-API

קבלת טוקן הצרכן (מפתח ה-API) של האפליקציה

פרטי הכניסה של האפליקציה (מוצר API, טוקן צרכן וסוד) מוחזרים כחלק מפרופיל האפליקציה. אדמין בארגון יכול לאחזר את טוקן הצרכן בכל שלב.

בפרופיל האפליקציה מוצגים הערך של טוקן הצרכן והסוד, הסטטוס של טוקן הצרכן וכל שיוך של מוצר API למפתח. אדמינים יכולים לאחזר את פרופיל טוקן הצרכן בכל שלב באמצעות Get Key Details for a Developer App 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

דוגמה לתשובה

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

מידע נוסף זמין במאמר קבלת פרטים על מפתח של אפליקציה למפתחים.

הוספת מוצר API לאפליקציה ולמפתח

כדי לעדכן אפליקציה ולהוסיף לה מוצר API חדש, צריך להוסיף את מוצר ה-API למפתח של האפליקציה באמצעות Add API Product to Key API. מידע נוסף זמין במאמר הוספת מוצר API למפתח.

הוספת מוצר API למפתח של אפליקציה מאפשרת לאפליקציה שמחזיקה במפתח לגשת למשאבי ה-API שכלולים במוצר ה-API. הפעלת ה-method הבאה מוסיפה מוצר API חדש לאפליקציה:

$ 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 

דוגמה לתשובה:

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

אישור טוקנים של צרכנים

הגדרת סוג האישור לידני מאפשרת לכם לשלוט במפתחים שיכולים לגשת למשאבים שמוגנים על ידי מוצרי API. כשמאשרים מפתחות במוצרי API, צריך לאשר מפתחות צרכנים באופן מפורש.manual אפשר לאשר מפתחות באופן מפורש באמצעות API‏ Approve or Revoke Specific Key of Developer App:

$ 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

דוגמה לתשובה

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

מידע נוסף זמין במאמר אישור או ביטול של מפתח ספציפי באפליקציית מפתח.

אישור מוצרי API למפתחות צרכן

גם לשיוך של מוצר API לטוקן צרכן יש סטטוס. כדי שהגישה ל-API תצליח, טוקן הצרכן צריך להיות מאושר וגם מאושר למוצר ה-API המתאים. אפשר לאשר את השיוך של טוקן צרכן למוצר API באמצעות API‏ Approve or Revoke API Product for a Key for a Developer App:

$ 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

פקודת ה-cURL הזו לא מחזירה תגובה. מידע נוסף זמין במאמר אישור או ביטול של מוצר API עבור מפתח של אפליקציה למפתחים.

ביטול מוצרי API עבור מפתחות צרכן

יכולות להיות הרבה סיבות לכך שתצטרכו לבטל את השיוך של מפתח צרכן למוצר API. יכול להיות שתצטרכו להסיר מוצר API מטוקן צרכן בגלל אי תשלום מצד המפתח, תקופת ניסיון שהסתיימה או כשמקדמים אפליקציה ממוצר API אחד למוצר API אחר.

כדי לבטל את השיוך של טוקן צרכן למוצר API, משתמשים ב-API‏ Approve או Revoke Specific Key of Developer App , באמצעות הפעולה revoke נגד טוקן הצרכן של אפליקציית המפתח:

$ 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

פקודת ה-cURL הזו לא מחזירה תגובה. מידע נוסף זמין במאמר אישור או ביטול של מפתח ספציפי באפליקציית מפתח.

אכיפה של הגדרות מוצר API

כדי לאכוף מוצרי API, צריך לצרף את אחד מסוגי המדיניות הבאים לזרימת ה-API proxy:

• VerifyAPIKey: מקבל הפניה למפתח API, מוודא שהוא מייצג אפליקציה תקפה ומתאים למוצר ה-API. מידע נוסף זמין במאמר מדיניות בנושא אימות מפתחות API.
• ‫OAuthV1, פעולה VerifyAccessToken: מאמתת את החתימה, מאמתת אסימון גישה מסוג OAuth 1.0a וטוקן צרכן, ומתאימה את האפליקציה למוצר ה-API. התמיכה ב-OAuth 1.0a הוצאה משימוש. אפשר לעיין במאמר בנושא תכונות שהוצאו משימוש.
• ‫OAuthV2, פעולת VerifyAccessToken: מאמתת שאסימון הגישה מסוג OAuth 2.0 תקף, מתאימה את האסימון לאפליקציה, מאמתת שהאפליקציה תקפה ואז מתאימה את האפליקציה למוצר API. מידע נוסף זמין במאמר בנושא דף הבית של OAuth.

אחרי שמגדירים את כללי המדיניות ואת מוצרי ה-API, מתבצע התהליך הבא ב-Apigee Edge:

1. בקשה מתקבלת על ידי Apigee Edge ומועברת לשרת ה-proxy המתאים של ה-API.
2. מדיניות מופעלת כדי לאמת את מפתח ה-API או את אסימון הגישה מסוג OAuth שהוצגו על ידי הלקוח.
3. ‫Edge מפענח את מפתח ה-API או את טוקן הגישה לפרופיל של אפליקציה.
4. ‫Edge פותר את הרשימה (אם יש) של מוצרי API שמשויכים לאפליקציה.
5. המוצר הראשון ב-API שתואם משמש לאכלוס משתני המכסה.
6. אם אין מוצר API שתואם למפתח ה-API או לטוקן הגישה, הבקשה נדחית.
7. ‫Edge אוכף בקרת גישה מבוססת URI (סביבה, שרת proxy ל-API ונתיב URI) על סמך הגדרות מוצר ה-API, יחד עם הגדרות המכסה.