أنت تعرض مستندات Apigee Edge.
انتقل إلى
مستندات Apigee X. معلومات

المزايا
تتيح لك سياسة "مفتاح واجهة برمجة التطبيقات" (Verify API Key) فرض التحقُّق من مفاتيح واجهة برمجة التطبيقات في وقت التشغيل، مع السماح فقط التطبيقات التي تمتلك مفاتيح واجهة برمجة تطبيقات معتمدة يمكنها الوصول إلى واجهات برمجة التطبيقات. تضمن هذه السياسة أن تكون مفاتيح واجهة برمجة التطبيقات صالحة، وأن تتضمّن لم يتم إبطالها، وتمت الموافقة على استهلاكها للموارد المحددة المرتبطة بواجهة برمجة التطبيقات المنتجات.
نماذج
المفتاح في معلمة طلب البحث
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
في هذا المثال، تتوقع السياسة العثور على مفتاح واجهة برمجة التطبيقات في متغيّر التدفق المسمى
request.queryparam.apikey
المتغيّر request.queryparam.{name}
هو متغير تدفق Edge قياسي تتم تعبئته بقيمة معلَمة طلب البحث التي تم تمريرها
في طلب العميل.
ينقل الأمر curl
التالي مفتاح واجهة برمجة التطبيقات في مَعلمة طلب بحث:
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 التالي كيفية تمرير مفتاح واجهة برمجة التطبيقات في عنوان:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
مفتاح في المتغيّر
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
ويمكن أن تشير السياسة إلى أي متغيّر يحتوي على المفتاح. السياسة في هذا المثال لاستخراج مفتاح واجهة برمجة التطبيقات من متغيّر باسم 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 مجموعة من متغيّرات التدفق تلقائيًا عند تنفيذ مفتاح Verify API. لمفتاح واجهة برمجة تطبيقات صالح. يمكنك استخدام هذه المتغيّرات للوصول إلى معلومات مثل التطبيق. الاسم ورقم تعريف التطبيق ومعلومات عن المطوّر أو الشركة التي سجّلت التطبيق في جلسة المعمل، كما هو موضح أعلاه، يمكنك استخدام سياسة "تعيين رسالة" للوصول إلى الاسم الأول للمطوِّر وآخر وعنوان البريد الإلكتروني بعد تنفيذ مفتاح التحقق من واجهة برمجة التطبيقات.
يسبق كل هذه المتغيرات:
verifyapikey.{policy_name}
في هذا المثال، يكون اسم سياسة "التحقّق من مفتاح واجهة برمجة التطبيقات" هو verify-api-key". لذلك، يمكنك الرجوع
الاسم الأول لمطوّر البرامج الذي قدّم الطلب من خلال الوصول إلى
المتغيّر verifyapikey.verify-api-key.developer.firstName.
تعلم Edge
لمحة عن سياسة "مفتاح واجهة برمجة التطبيقات" (Verify API)
عندما يسجّل أحد المطوّرين تطبيقًا على Edge، ينشئ Edge مفتاح العميل تلقائيًا زوجًا سريًا. يمكنك الاطّلاع على مفتاح العميل ومفتاح السر للتطبيق في واجهة مستخدم Edge أو يمكنك الوصول إليهما. من واجهة برمجة تطبيقات Edge.
في وقت تسجيل التطبيق، يختار المطوِّر واحدًا أو أكثر من منتجات واجهة برمجة التطبيقات من أجل ربطها بالتطبيق، حيث يكون منتج واجهة برمجة التطبيقات عبارة عن مجموعة من الموارد من خلال الخوادم الوكيلة لواجهة برمجة التطبيقات. بعد ذلك، يمرّر المطوّر مفتاح واجهة برمجة التطبيقات (مفتاح المستهلك) كجزء من كل طلب إلى واجهة برمجة تطبيقات في منتج واجهة برمجة تطبيقات مرتبط بالتطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على القسم نظرة عامة على النشر.
يمكن استخدام مفاتيح واجهة برمجة التطبيقات كرموز للمصادقة، أو يمكن استخدامها للحصول على إمكانية الدخول عبر بروتوكول OAuth الرموز المميزة. في بروتوكول OAuth، يُشار إلى مفاتيح واجهة برمجة التطبيقات باسم "معرّف العميل". ويمكن استخدام الأسماء بالتبادل. يُرجى الاطِّلاع على صفحة OAuth الرئيسية لمزيد من المعلومات.
يملأ 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 |
الاسم الداخلي للسياسة. يمكن لقيمة السمة يمكنك، إذا أردت، استخدام العنصر |
لا ينطبق | مطلوب |
continueOnError |
اضبط القيمة على يمكنك ضبط القيمة على |
خطأ | اختياري |
enabled |
اضبط القيمة على اضبط القيمة على |
صحيح | اختياري |
async |
تم إيقاف هذه السمة نهائيًا. |
خطأ | منهي العمل به |
<DisplayName> عنصر
استخدِمه مع السمة name
لتصنيف السياسة في
إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.
<DisplayName>Policy Display Name</DisplayName>
تلقائي |
لا ينطبق إذا لم تستخدم هذا العنصر، سيتم ضبط قيمة السمة |
---|---|
التواجد في المنزل | اختياري |
النوع | سلسلة |
<APIKey> عنصر
يحدّد هذا العنصر متغيّر التدفق الذي يحتوي على مفتاح واجهة برمجة التطبيقات يرسل العميل عادةً مفتاح واجهة برمجة التطبيقات
في معلَمة طلب بحث أو عنوان HTTP أو معلَمة نموذج. فعلى سبيل المثال، إذا تم إرسال المفتاح في عنوان
يُسمى x-apikey
، فسيتم العثور على المفتاح في المتغير: request.header.x-apikey
تلقائي | غير متاح |
---|---|
التواجد في المنزل | مطلوب |
النوع | سلسلة |
السمات
يوضّح الجدول التالي سمات العنصر <APIKey>
.
السمة | الوصف | تلقائي | التواجد في المنزل |
---|---|---|---|
المرجع |
يشير إلى مرجع للمتغيّر الذي يحتوي على مفتاح واجهة برمجة التطبيقات. يُسمَح باستخدام موقع جغرافي واحد فقط. لكل سياسة. |
لا ينطبق | مطلوب |
أمثلة
في هذه الأمثلة، يتم تمرير المفتاح في المَعلمات وعنوانًا باسم 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 مجموعة من التدفقات. المتغيرات. تتوفر هذه المتغيرات للسياسات أو التعليمة البرمجية التي يتم تنفيذها لاحقًا في التدفق، تُستخدم غالبًا لإجراء معالجة مخصصة بناءً على سمات مفتاح واجهة برمجة التطبيقات مثل اسم التطبيق، منتج واجهة برمجة التطبيقات المستخدم لتفويض المفتاح أو السمات المخصصة لمفتاح واجهة برمجة التطبيقات.
تملأ السياسة عدة أنواع مختلفة من متغيّرات التدفق، بما في ذلك:
- بنود عامة
- تطبيق
- مطور التطبيق
- الشركة
- الإحصاءات
لكل نوع من متغيرات التدفق بادئة مختلفة. تُعد جميع المتغيرات أعدادًا قياسية باستثناء يشار إليها على وجه التحديد على أنها مصفوفات.
متغيرات التدفق العامة
يسرد الجدول التالي متغيّرات التدفق العامة التي تمّت تعبئتها بسياسة "مفتاح التحقّق من واجهة برمجة التطبيقات" (Verify API Key). يسبق كل هذه المتغيرات:
verifyapikey.{policy_name}
مثلاً: verifyapikey.{policy_name}.client_id
وتشمل المتغيرات المتاحة ما يلي:
متغير | الوصف |
---|---|
client_id |
مفتاح المستهلك (المعروف أيضًا بمفتاح واجهة برمجة التطبيقات أو مفتاح التطبيق) الذي يوفّره التطبيق الذي يقدّم الطلب |
client_secret |
سر العميل المرتبط بمفتاح العميل. |
redirection_uris |
أي معرّفات موارد منتظمة (URI) لإعادة التوجيه في الطلب. |
developer.app.id |
رقم تعريف تطبيق المطوِّر الذي قدّم الطلب. |
developer.app.name |
اسم تطبيق المطوّر الذي قدّم الطلب |
developer.id |
رقم تعريف المطوّر المسجَّل كمالك للتطبيق الذي قدّم الطلب |
developer.{custom_attrib_name} |
أي سمات مخصّصة مشتقة من الملف الشخصي لمفتاح التطبيق. |
DisplayName |
قيمة <DisplayName> للسياسة . |
failed |
ضبط على "صحيح" عند تعذُّر التحقّق من صحة مفتاح واجهة برمجة التطبيقات |
{custom_app_attrib} |
أي سمة مخصّصة مشتقة من الملف الشخصي للتطبيق. تحديد اسم مخصّص . |
apiproduct.name* |
اسم منتج واجهة برمجة التطبيقات المُستخدَم للتحقّق من الطلب. |
apiproduct.{custom_attrib_name}* |
أي سمة مخصّصة مشتقة من الملف الشخصي لمنتج واجهة برمجة التطبيقات. |
apiproduct.developer.quota.limit* |
تمثّل هذه السمة الحدّ الأقصى للحصة المحدّدة في منتج واجهة برمجة التطبيقات، إن توفّر. |
apiproduct.developer.quota.interval* |
تمثّل هذه السمة الفاصل الزمني للحصة المحدّدة في منتج واجهة برمجة التطبيقات، إن توفّر. |
apiproduct.developer.quota.timeunit* |
تمثّل هذه السمة وحدة وقت الحصة المحدّدة في منتج واجهة برمجة التطبيقات، إن توفّرت. |
* تتم تعبئة متغيّرات منتجات واجهة برمجة التطبيقات تلقائيًا إذا كانت منتجات واجهة برمجة التطبيقات
باستخدام بيئة وخوادم وكيل وموارد صالحة (مشتقة من
proxy.pathsuffix ). للحصول على تعليمات حول إعداد منتجات واجهة برمجة التطبيقات، راجع
استخدام الحافة
Management API لنشر واجهات برمجة التطبيقات. |
متغيّرات مسار التطبيق
تتم تعبئة متغيّرات التدفق التالية التي تحتوي على معلومات عن التطبيق من خلال السياسة. يسبق كل هذه المتغيرات:
verifyapikey.{policy_name}.app
.
على سبيل المثال:
verifyapikey.{policy_name}.app.name
وتشمل المتغيرات المتاحة ما يلي:
متغير | الوصف |
---|---|
name |
اسم التطبيق |
id |
رقم تعريف التطبيق |
accessType |
غير مُستخدَم في Apigee. |
callbackUrl |
عنوان URL لمعاودة الاتصال بالتطبيق. يُستخدَم عادةً لـ OAuth فقط. |
DisplayName |
الاسم المعروض للتطبيق |
status |
حالة التطبيق، مثل "تمت الموافقة عليه" أو "إبطال". |
apiproducts |
مصفوفة تحتوي على قائمة بمنتجات واجهة برمجة التطبيقات المرتبطة بالتطبيق. |
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 |
حالة مالك التطبيق، مثل "نشط" أو "غير نشط" أو "تسجيل الدخول"
|
created_at |
طابع التاريخ/الوقت الذي تم فيه إنشاء الشركة. |
created_by |
عنوان البريد الإلكتروني للمستخدم الذي أنشأ الشركة. |
last_modified_at |
طابع التاريخ/الوقت الذي تم فيه إجراء آخر تعديل على الشركة. |
last_modified_by |
عنوان البريد الإلكتروني للمستخدم الذي عدّل الشركة آخر مرة. |
{company_custom_attributes} |
تمثّل هذه السمة أي سمة مخصّصة للشركة. حدِّد اسم السمة المخصّصة. |
المتغيّرات في "إحصاءات Google"
تتم تعبئة المتغيّرات التالية تلقائيًا في "إحصاءات Google" عند تطبيق سياسة "مفتاح واجهة برمجة التطبيقات" (Verify API Key). لمفتاح واجهة برمجة تطبيقات صالح. لا تتم تعبئة هذه المتغيّرات إلا من خلال مفتاح التحقّق من واجهة برمجة التطبيقات. وسياسات OAuth.
ويمكن استخدام المتغيرات والقيم كأبعاد لإنشاء تقارير في Analytics من أجل تحقيق إحصاءات عن أنماط الاستهلاك من قِبل المطوّرين والتطبيقات
- apiproduct.name
- developer.app.name
- client_id
- developer.id
مرجع الخطأ
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | The Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive, you cannot access the developers or apps associated with that Company. An org admin can change a Company's status using the management API. See Set the Status of a Company. |
keymanagement.service.DeveloperStatusNotActive |
401 |
The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways:
|
keymanagement.service.invalid_client-app_not_approved |
401 | The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee Edge. An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App. |
oauth.v2.FailedToResolveAPIKey |
401 | The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved). |
oauth.v2.InvalidApiKey |
401 | An API key was received by Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Register apps and manage API keys. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product. |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
SpecifyValueOrRefApiKey |
The <APIKey> element does not have a value or key specified. |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.VK-VerifyAPIKey.failed = true |
Example error responses
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Example fault rule
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>