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

$ 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 עבור המפתח. כאדמינים, תוכלו לאחזר את פרופיל מפתח צרכן בכל עת באמצעות הדף קבל פרטים עיקריים עבור אפליקציה למפתחים 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 חדש app:

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

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

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

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