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 مربوط به ایجاد محصول 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 یکسان را فراهم می‌کنند، اما با تنظیمات سهمیه‌بندی مرتبط متفاوت.

تنظیمات پیکربندی محصول 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 است ثبت می‌کند و زیرمجموعه‌ای از ویژگی‌های کسب درآمد را با استفاده از 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 «افزودن محصول 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. اج، کلید API یا توکن دسترسی را به پروفایل برنامه تبدیل می‌کند.
4. اج (در صورت وجود) فهرست محصولات API مرتبط با برنامه را بررسی می‌کند.
5. اولین محصول API که مطابقت داشته باشد، برای پر کردن متغیرهای Quota استفاده می‌شود.
6. اگر هیچ محصول API با کلید API یا توکن دسترسی مطابقت نداشته باشد، درخواست رد می‌شود.
7. اج، کنترل دسترسی مبتنی بر URI (محیط، پروکسی API و مسیر URI) را بر اساس تنظیمات محصول 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 مربوط به ایجاد محصول 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 یکسان را فراهم می‌کنند، اما با تنظیمات سهمیه‌بندی مرتبط متفاوت.

تنظیمات پیکربندی محصول 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 است ثبت می‌کند و زیرمجموعه‌ای از ویژگی‌های کسب درآمد را با استفاده از 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 «افزودن محصول 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. اج، کلید API یا توکن دسترسی را به پروفایل برنامه تبدیل می‌کند.
4. اج (در صورت وجود) فهرست محصولات API مرتبط با برنامه را بررسی می‌کند.
5. اولین محصول API که مطابقت داشته باشد، برای پر کردن متغیرهای Quota استفاده می‌شود.
6. اگر هیچ محصول API با کلید API یا توکن دسترسی مطابقت نداشته باشد، درخواست رد می‌شود.
7. اج، کنترل دسترسی مبتنی بر URI (محیط، پروکسی API و مسیر URI) را بر اساس تنظیمات محصول API، همراه با تنظیمات سهمیه، اعمال می‌کند.