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

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

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

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

מוצרי API מאפשרים למפתחים לרשום אפליקציות שצורכות ממשקי API באמצעות מפתחות API ואסימוני גישה מסוג OAuth. מוצרי 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 של מוצרי List 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 or 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 v1.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, וגם על סמך הגדרות מכסה.