פרסום ממשקי 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 שנחשפו על ידי שרת ה-API של שרת ה-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 שהגישה אליהם מתבצעת דרך שרת ה-API של שרת ה-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 ל-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 למפתח האפליקציה באמצעות הוספת מוצר API ל-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 של אישור או ביטול של מפתח ספציפי של אפליקציה למפתחים:

$ 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 של אישור או ביטול של ממשק API עבור מפתח של אפליקציה למפתחים:

$ 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 לאישור או ביטול של מפתח ספציפי של אפליקציה למפתחים , תוך שימוש בפעולת הביטול של הפעולה מול מפתח הצרכן של האפליקציה שמפתחת:

$ 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 את אחד מסוגי המדיניות הבאים:

• verificationAPIKey: מקבל הפניה למפתח 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 ומנותבת לשרת ה-API המתאים.
2. הופעלה מדיניות שמאמתת את מפתח ה-API או את אסימון הגישה ל-OAuth שמוצג על ידי הלקוח.
3. Edge סורק את מפתח ה-API או את אסימון הגישה לפרופיל אפליקציה.
4. Edge פותר את הרשימה (אם יש) של מוצרי ה-API המשויכים לאפליקציה.
5. מוצר ה-API הראשון שתואם משמש לאכלוס משתני Quota.
6. אם אין מוצר API שתואם למפתח ה-API או לאסימון הגישה, הבקשה תידחה.
7. Edge אוכפת בקרת גישה שמבוססת על URI (סביבה, שרת proxy של API ונתיב URI) על סמך הגדרות המוצר של ה-API, וגם הגדרות מכסה.