API ها را با استفاده از Edge API منتشر کنید

شما در حال مشاهده اسناد 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 Product API مراجعه کنید.

درخواست زیر یک محصول API به نام weather_free ایجاد می‌کند. محصول 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 ایجاد شده در بالا ابتدایی ترین سناریو را پیاده سازی می کند و درخواست ها را به یک پروکسی API در یک محیط مجاز می کند. یک محصول API را تعریف می کند که به یک برنامه مجاز امکان می دهد به هر منبع API دسترسی یافته از طریق پراکسی API در حال اجرا در محیط آزمایشی دسترسی داشته باشد. محصولات API تنظیمات پیکربندی اضافی را نشان می دهند که به شما امکان می دهد کنترل دسترسی به API های خود را برای گروه های مختلف توسعه دهندگان سفارشی کنید. به عنوان مثال می توانید دو محصول API ایجاد کنید که دسترسی به پراکسی های API مختلف را فراهم می کند. همچنین می‌توانید دو محصول API ایجاد کنید که دسترسی به پراکسی‌های API یکسان، اما با تنظیمات Quota مرتبط متفاوت را فراهم می‌کنند.

تنظیمات پیکربندی محصول 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، scope ها کاملا اختیاری هستند. برای دستیابی به مجوز دقیق تر می توانید از اسکوپ استفاده کنید. هر کلید مصرف‌کننده‌ای که برای یک برنامه صادر می‌شود با یک «حوزه اصلی» مرتبط است. محدوده اصلی مجموعه ای از تمام دامنه ها در همه محصولات 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 برای کلید را نشان می دهد. به‌عنوان یک سرپرست، می‌توانید در هر زمان با استفاده از دریافت جزئیات کلیدی برای 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 دسترسی پیدا کند. فراخوانی روش زیر یک محصول 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 متصل شود:

• 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 دریافت می‌شود و به پروکسی API مناسب هدایت می‌شود.
2. خط مشی ای اجرا می شود که کلید API یا نشانه دسترسی OAuth ارائه شده توسط مشتری را تأیید می کند.
3. Edge کلید API یا نشانه دسترسی به نمایه برنامه را حل می کند.
4. Edge لیست (در صورت وجود) محصولات API مرتبط با برنامه را حل می کند.
5. اولین محصول API که مطابقت دارد برای پر کردن متغیرهای Quota استفاده می شود.
6. اگر هیچ محصول API با کلید API یا نشانه دسترسی مطابقت نداشته باشد، درخواست رد می شود.
7. Edge کنترل دسترسی مبتنی بر URI (محیط، پروکسی API و مسیر URI) را بر اساس تنظیمات محصول API به همراه تنظیمات Quota اعمال می‌کند.