درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
چه
خطمشی «درستیسنجی کلید میانای برنامهسازی کاربردی» به شما امکان میدهد درستیسنجی کلیدهای میانای برنامهسازی کاربردی را در زمان اجرا اعمال کنید و فقط به برنامههایی که کلیدهای میانای برنامهسازی کاربردی تأییدشده دارند اجازه دهید به میاناهای برنامهسازی کاربردی شما دسترسی داشته باشند. این خطمشی تضمین میکند که کلیدهای API معتبر باشند، لغو نشده باشند، و برای مصرف منابع خاص مرتبط با محصولات API شما تأیید شده باشند.
نمونهها
کلید در پارامتر پُرسمان
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>در این مثال، خطمشی انتظار دارد کلید میانای برنامهسازی کاربردی را در متغیر جاریای بهنام
request.queryparam.apikey پیدا کند. متغیر request.queryparam.{name}
یک متغیر استاندارد جریان Edge است که با مقدار پارامتر پُرسمان منتقلشده
در درخواست کارخواه تکمیل میشود.
فرمان curl زیر کلید API را در یک پارامتر پُرسمان ارسال میکند:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
کلید در سرایند
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>در این مثال، خطمشی انتظار دارد کلید میانای برنامهسازی کاربردی را در متغیر جاریای بهنام
request.header.x-apikey پیدا کند. متغیر request.header.{name}
متغیر جریان استاندارد Edge است که با مقدار سرایندی که در
درخواست کارخواه ارسال شده است تکمیل میشود.
دستور cURL زیر نحوه ارسال کلید API در سرایند را نشان میدهد:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
کلید در متغیر
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>خطمشی میتواند به هر متغیری که حاوی کلید است ارجاع دهد. خطمشی در این مثال کلید API را از متغیری بهنام requestAPIKey.key استخراج میکند.
نحوه پر شدن آن متغیر به شما بستگی دارد. برای مثال، میتوانید از خطمشی «استخراج متغیرها» برای تکمیل requestAPIKey.key از پارامتر پُرسمان بهنام myKey استفاده کنید، همانطور که در زیر نشان داده شده است:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
<Source>request</Source>
<QueryParam name="myKey">
<Pattern ignoreCase="true">{key}</Pattern>
</QueryParam>
<VariablePrefix>requestAPIKey</VariablePrefix>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>متغیرهای جاری خطمشی دسترسی
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
وقتی خطمشی «درستیسنجی کلید میانای برنامهسازی کاربردی» برای کلید میانای برنامهسازی کاربردی معتبر اجرا میشود، Edge بهطور خودکار مجموعهای از متغیرهای جریان را تکمیل میکند. میتوانید از این متغیرها برای دسترسی به اطلاعاتی مثل نام برنامه، شناسه برنامه، و اطلاعات مربوط به توسعهدهنده یا شرکتی که برنامه را ثبت کرده است استفاده کنید. در مثال بالا، از خطمشی «اختصاص پیام» برای دسترسی به نام کوچک، نام خانوادگی، و نشانی ایمیل توسعهدهنده پساز اجرای «درستیسنجی کلید API» استفاده میکنید.
همه این متغیرها با پیشوند زیر شروع میشوند:
verifyapikey.{policy_name}در این مثال، نام خطمشی «درستیسنجی کلید API» عبارت «verify-api-key» است. بنابراین، با دسترسی به متغیر verifyapikey.verify-api-key.developer.firstName.، به نام توسعهدهندهای که درخواست را انجام میدهد ارجاع میدهید
آشنایی با Edge
درباره خطمشی «درستیسنجی کلید میانای برنامهسازی کاربردی»
وقتی توسعهدهندهای برنامهای را در Edge ثبت میکند، Edge بهطور خودکار یک جفت کلید مصرفکننده و رمز تولید میکند. میتوانید جفت کلید مصرفکننده و رمز برنامه را در «واسط کاربر Edge» ببینید یا ازطریق Edge API به آنها دسترسی پیدا کنید.
در زمان ثبت برنامه، توسعهدهنده یک یا چند محصول API را برای ارتباط با برنامه انتخاب میکند، که در آن محصول API مجموعهای از منابع قابلدسترس ازطریق پراکسیهای API است. سپس توسعهدهنده کلید API (کلید مصرفکننده) را بهعنوان بخشی از هر درخواست به API در محصول API مرتبط با برنامه ارسال میکند. برای اطلاعات بیشتر، نمای کلی انتشار را ببینید.
از کلیدهای API میتوان بهعنوان کدهای اصالتسنجی استفاده کرد، یا میتوان از آنها برای دریافت کدهای دسترسی OAuth استفاده کرد. در OAuth، کلیدهای API بهعنوان «شناسه کارخواه» نامیده میشوند. این نامها را میتوان بهجای یکدیگر استفاده کرد. برای اطلاعات بیشتر، صفحه اصلی OAuth را ببینید.
وقتی خطمشی «درستیسنجی کلید API» اجرا میشود، Edge بهطور خودکار مجموعهای از متغیرهای جریان را تکمیل میکند. برای اطلاعات بیشتر، متغیرهای جریان را در زیر ببینید.
مرجع عنصر
در زیر عناصر و مشخصههایی را که میتوانید در این خطمشی پیکربندی کنید مشاهده میکنید:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
مشخصههای <VerifyAPIKey>
مثال زیر مشخصههای برچسب <VerifyAPIKey> را نشان میدهد:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:
| صفت | توضیحات | پیش فرض | حضور |
|---|---|---|---|
name | نام داخلی سیاست. مقدار مشخصه در صورت تمایل، از عنصر | N/A | مورد نیاز |
continueOnError | برای بازگرداندن خطا در صورت شکست خط مشی، روی روی | نادرست | اختیاری |
enabled | برای اجرای خط مشی روی برای خاموش کردن خط مشی، روی | درست است | اختیاری |
async | این ویژگی منسوخ شده است. | نادرست | منسوخ شده است |
عنصر <DisplayName>
علاوه بر ویژگی name برای برچسبگذاری خطمشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.
<DisplayName>Policy Display Name</DisplayName>
| پیش فرض | N/A اگر این عنصر را حذف کنید، از مقدار ویژگی |
|---|---|
| حضور | اختیاری |
| تایپ کنید | رشته |
عنصر <APIKey>
این عنصر متغیر جاریسازی را که حاوی کلید API است مشخص میکند. معمولاً، کارخواه کلید API را در پارامتر پُرسمان، سرایند HTTP، یا پارامتر فرم ارسال میکند. برای مثال، اگر کلید در سرایندی به نام x-apikey ارسال شود، کلید در متغیر request.header.x-apikey پیدا خواهد شد
| پیشفرض | NA |
|---|---|
| حضور | الزامی |
| نوع | رشته |
مشخصهها
جدول زیر مشخصههای عنصر <APIKey> را شرح میدهد
| مشخصه | شرح | پیشفرض | حضور |
|---|---|---|---|
| مرجع |
مرجعی به متغیری که حاوی کلید API است. فقط یک مکان برای هر خطمشی مجاز است. |
موجود نیست | الزامی |
مثالها
در این مثالها، کلید در پارامترها و سرایندی بهنام x-apikey ارسال میشود.
بهعنوان پارامتر پُرسمان:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>بهعنوان سرصفحه HTTP:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>بهعنوان پارامتر فرم HTTP:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>طرحوارهها
متغیرهای جریان
وقتی خطمشی «درستیسنجی کلید میانای برنامهسازی کاربردی» روی کلید میانای برنامهسازی کاربردی معتبری اعمال میشود، Edge مجموعهای از متغیرهای جریان را تکمیل میکند. این متغیرها برای خطمشیها یا کدی که بعداً در جریان اجرا میشود دردسترس هستند و اغلب برای انجام پردازش سفارشی براساس مشخصههای کلید API مثل نام برنامه، محصول API مورداستفاده برای مجاز کردن کلید، یا مشخصههای سفارشی کلید API استفاده میشوند.
این خطمشی چندین نوع مختلف از متغیرهای جریان را پر میکند، ازجمله:
- عمومی
- برنامه
- توسعهدهنده
- شرکت
- Analytics
هر نوع متغیر جاری پیشوند متفاوتی دارد. همه متغیرها اسکالر هستند بهجز مواردی که بهطور خاص بهعنوان آرایه مشخص شدهاند.
متغیرهای جریان عمومی
جدول زیر متغیرهای جریان کلی را که توسط خطمشی «تأیید کلید API» پر شدهاند فهرست میکند. همه این متغیرها با پیشوند زیر شروع میشوند:
verifyapikey.{policy_name}برای مثال: verifyapikey.{policy_name}.client_id
متغیرهای دردسترس شامل موارد زیر میشود:
| متغیر | شرح |
|---|---|
client_id |
کلید مصرفکننده (معروف به کلید API یا کلید برنامه) که توسط برنامه درخواستکننده ارائه شده است. |
client_secret |
رمز مصرفکننده مرتبط با کلید مصرفکننده. |
redirection_uris |
هر نشانی وب هدایت در درخواست. |
developer.app.id |
شناسه برنامه توسعهدهندهای که درخواست را ارسال میکند. |
developer.app.name |
نام برنامه توسعهدهنده که درخواست را ارائه میکند. |
developer.id |
شناسه توسعهدهندهای که بهعنوان مالک برنامه درخواستکننده ثبت شده است. |
developer.{custom_attrib_name} |
هرگونه مشخصه سفارشی استخراجشده از نمایه کلید برنامه |
DisplayName |
مقدار مشخصه <DisplayName> خطمشی. |
failed |
وقتی درستیسنجی «کلید میانای برنامهسازی کاربردی» ناموفق باشد، روی «درست» تنظیم میشود. |
{custom_app_attrib} |
هر مشخصه سفارشی برگرفته از نمایه برنامه. نام مشخصه سفارشی را مشخص کنید. |
apiproduct.name* |
نام محصول API که برای اعتبارسنجی درخواست استفاده میشود. |
apiproduct.{custom_attrib_name}* |
هر مشخصه سفارشی که از نمایه محصول API استخراج شده باشد. |
apiproduct.developer.quota.limit* |
حد سهمیه تنظیمشده در محصول API، درصورت وجود. |
apiproduct.developer.quota.interval* |
فاصله سهمیه تنظیمشده در محصول API، درصورت وجود. |
apiproduct.developer.quota.timeunit* |
واحد زمان سهمیه تنظیمشده در محصول API، درصورت وجود. |
* اگر محصولات API با محیط، پراکسیها، و منابع معتبر پیکربندی شده باشند (مشتق از proxy.pathsuffix)، متغیرهای محصول API بهطور خودکار تکمیل میشوند. برای دستورالعملهای راهاندازی محصولات API، به استفاده از Edge
management API برای انتشار API مراجعه کنید. |
|
متغیرهای جریان برنامه
متغیرهای جریان زیر که حاوی اطلاعاتی درباره برنامه است توسط خطمشی تکمیل میشود. همه این متغیرها با پیشوند زیر شروع میشوند:
verifyapikey.{policy_name}.app.
برای مثال:
verifyapikey.{policy_name}.app.name
متغیرهای دردسترس شامل موارد زیر میشود:
| متغیر | شرح |
|---|---|
name |
نام برنامه. |
id |
شناسه برنامه. |
accessType |
Apigee از آن استفاده نمیکند. |
callbackUrl |
نشانی وب برگشتی برنامه. معمولاً فقط برای OAuth استفاده میشود. |
DisplayName |
نام نمایشی برنامه. |
status |
وضعیت برنامه، مانند «تأییدشده» یا «لغوشده». |
apiproducts |
آرایهای حاوی فهرست محصولات API مرتبط با برنامه. |
appFamily |
هر خانواده برنامهای که برنامه در آن قرار دارد، یا «پیشفرض». |
appParentStatus |
وضعیت ولی برنامه، مثل «فعال» یا «غیرفعال» |
appType |
نوع برنامه، بهصورت «شرکت» یا «توسعهدهنده». |
appParentId |
شناسه برنامه والد. |
created_at |
مُهر تاریخ/زمان ایجاد برنامه. |
created_by |
نشانی ایمیل توسعهدهندهای که برنامه را ساخته است. |
last_modified_at |
مُهر تاریخ/زمان آخرین بهروزرسانی برنامه. |
last_modified_by |
نشانی ایمیل توسعهدهندهای که آخرین بار برنامه را بهروزرسانی کرده است. |
{app_custom_attributes} |
هر مشخصه برنامه سفارشی. نام مشخصه سفارشی را مشخص کنید. |
متغیرهای جاری توسعهدهنده
متغیرهای جریان زیر که حاوی اطلاعاتی درباره توسعهدهنده است توسط خطمشی پر میشود. همه این متغیرها با پیشوند زیر شروع میشوند:
verifyapikey.{policy_name}.developerبرای مثال:
verifyapikey.{policy_name}.developer.id
متغیرهای دردسترس شامل موارد زیر میشود:
| متغیر | شرح |
|---|---|
id |
برمیگرداند {org_name}@@@{developer_id} |
userName |
نام کاربری توسعهدهنده. |
firstName |
نام توسعهدهنده. |
lastName |
نام خانوادگی توسعهدهنده. |
email |
نشانی ایمیل توسعهدهنده. |
status |
وضعیت توسعهدهنده، بهعنوان فعال، غیرفعال، یا login_lock. |
apps |
آرایهای از برنامههای منسوب به توسعهدهنده. |
created_at |
مهر تاریخ/زمان ایجاد توسعهدهنده. |
created_by |
نشانی ایمیل کاربری که توسعهدهنده را ایجاد کرده است. |
last_modified_at |
مُهر تاریخ/زمان آخرین تغییر توسعهدهنده. |
last_modified_by |
نشانی ایمیل کاربری که توسعهدهنده را اصلاح کرده است. |
{developer_custom_attributes} |
هر مشخصه سفارشی توسعهدهنده. نام مشخصه سفارشی را مشخص کنید. |
Company |
نام شرکت، درصورت وجود، مرتبط با توسعهدهنده. |
متغیرهای جریان شرکت
متغیرهای جریان زیر که حاوی اطلاعاتی درباره شرکت است توسط خطمشی تکمیل میشود. همه این متغیرها با پیشوند زیر شروع میشوند:
verifyapikey.{policy_name}.companyبرای مثال:
verifyapikey.{policy_name}.company.nameمتغیرهای دردسترس شامل موارد زیر میشود:
| متغیر | شرح |
|---|---|
name |
نام شرکت. |
displayName |
نام نمایشی شرکت. |
id |
شناسه شرکت. |
apps |
آرایهای حاوی فهرست برنامههای شرکت. |
appOwnerStatus |
وضعیت مالک برنامه، بهعنوان فعال، غیرفعال، یا login_lock.
|
created_at |
مهر تاریخ/زمان ایجاد شرکت. |
created_by |
نشانی ایمیل کاربری که شرکت را ایجاد کرده است. |
last_modified_at |
مُهر تاریخ/زمان آخرین اصلاح شرکت. |
last_modified_by |
نشانی ایمیل کاربری که آخرین بار شرکت را اصلاح کرده است. |
{company_custom_attributes} |
هر مشخصه سفارشی شرکت. نام مشخصه سفارشی را مشخص کنید. |
متغیرهای Analytics
متغیرهای زیر وقتی خطمشی «بهتأیید رساندن کلید میانای برنامهسازی کاربردی» برای کلید میانای برنامهسازی کاربردی معتبر اجرا میشود بهطور خودکار در Analytics تکمیل میشوند. این متغیرها فقط توسط خطمشی «درستیسنجی کلید میانای برنامهسازی کاربردی» و خطمشیهای OAuth تکمیل میشوند.
متغیرها و مقادیر میتوانند بهعنوان ابعاد برای ساختن گزارشهای Analytics استفاده شوند تا دید بهتری درباره الگوهای مصرف توسعهدهندگان و برنامهها بهدست آورید.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
مرجع خطا
این بخش کدهای خطا و پیامهای خطایی را که برگردانده میشوند و متغیرهای خطایی را که Edge هنگام راهاندازی خطا در این خطمشی تنظیم میکند شرح میدهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه میدهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خطمشی بدانیدو رسیدگی به اشکالات را ببینید.
خطاهای زمان اجرا
این خطاها ممکن است هنگام اجرای خطمشی رخ دهند.
| کد خطا | وضعیت HTTP | علت |
|---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | «شرکت» مرتبط با «برنامه توسعهدهنده» که کلید API مورد استفاده شما را دارد وضعیت غیرفعال دارد. وقتی وضعیت «شرکت» روی غیرفعال تنظیم شود، نمیتوانید به توسعهدهندگان یا برنامههای مرتبط با آن «شرکت» دسترسی داشته باشید. سرپرست سازمان میتواند وضعیت «شرکت» را بااستفاده از میانای برنامهسازی کاربردی مدیریت تغییر دهد. تنظیم وضعیت شرکت را ببینید. |
keymanagement.service.DeveloperStatusNotActive |
401 |
توسعهدهندهای که «برنامه توسعهدهنده» دارای کلید میانای برنامهسازی کاربردی مورد استفاده شما را ایجاد کرده است وضعیت غیرفعال دارد. وقتی وضعیت «توسعهدهنده نرمافزار» روی غیرفعال تنظیم شود، همه «برنامههای توسعهدهنده» ایجادشده توسط آن توسعهدهنده غیرفعال میشوند. کاربر سرپرست با اجازههای مناسب (مثل «سرپرست سازمان») میتواند وضعیت توسعهدهنده را به روشهای زیر تغییر دهد:
|
keymanagement.service.invalid_client-app_not_approved |
401 | «برنامه توسعهدهنده» مرتبط با کلید میانای برنامهسازی کاربردی باطل شده است. برنامه لغوشده نمیتواند به هیچیک از محصولات API دسترسی داشته باشد و نمیتواند هیچیک از APIهای مدیریتشده توسط Apigee Edge را فراخوانی کند. سرپرست سازمان میتواند وضعیت «برنامه توسعهدهنده» را بااستفاده از API مدیریت تغییر دهد. تأیید یا لغو برنامه توسعهدهنده را ببینید. |
oauth.v2.FailedToResolveAPIKey |
401 | خطمشی انتظار دارد کلید API را در متغیری که در عنصر <APIKey> خطمشی مشخص شده است پیدا کند. این خطا زمانی رخ میدهد که متغیر موردانتظار وجود نداشته باشد (قابلحل نباشد). |
oauth.v2.InvalidApiKey |
401 | کلید میانای برنامهسازی کاربردی توسط Edge دریافت شد، اما نامعتبر است. وقتی Edge کلید را در پایگاه داده خود جستجو میکند، باید دقیقاً با کلیدی که در درخواست ارسال شده مطابقت داشته باشد. اگر میانای برنامهسازی کاربردی قبلاً کار میکرد، مطمئن شوید کلید بازتولید نشده باشد. اگر کلید بازتولید شده باشد، اگر بخواهید از کلید قدیمی استفاده کنید، این خطا را خواهید دید. برای جزئیات، ثبت برنامهها و مدیریت کلیدهای میانای برنامهسازی کاربردی را ببینید. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | کلید میانای برنامهسازی کاربردی توسط Edge دریافت شده است و معتبر است؛ بااینحال، با کلید تأییدشده در «برنامه توسعهدهنده» منسوب به پراکسی میانای برنامهسازی کاربردی شما ازطریق «محصول» مطابقت ندارد. |
خطاهای استقرار
این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خطمشی را مستقر میکنید.
| نام خطا | علت |
|---|---|
SpecifyValueOrRefApiKey |
عنصر <APIKey> مقدار یا کلید مشخصشدهای ندارد. |
متغیرهای خطا
این متغیرها زمانی تنظیم میشوند که خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، آنچه باید درباره خطاهای خطمشی بدانیدرا ببینید.
| متغیر | مکان | مثال |
|---|---|---|
fault.name="fault_name" |
fault_name نام خطا است، همانطور که در جدول خطاهای زمان اجرا در بالا فهرست شده است. نام خطا آخرین بخش کد خطا است. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name نام مشخصشده کاربر برای خطمشیای است که خطا را ایجاد کرده است. | oauthV2.VK-VerifyAPIKey.failed = true |
نمونه پاسخهای خطا
{
"fault":{
"faultstring":"Invalid ApiKey",
"detail":{
"errorcode":"oauth.v2.InvalidApiKey"
}
}
}{
"fault":{
"detail":{
"errorcode":"keymanagement.service.DeveloperStatusNotActive"
},
"faultstring":"Developer Status is not Active"
}
}قانون خطای نمونه
<FaultRule name="FailedToResolveAPIKey">
<Step>
<Name>AM-FailedToResolveAPIKey</Name>
</Step>
<Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>