سياسة VerificationAPIKey

أنت تعرض مستندات 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>

&lt;VerifyAPIKey&gt; السمات

يوضّح المثال التالي السمات على العلامة <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

السمة الوصف تلقائي التواجد في المنزل
name

الاسم الداخلي للسياسة. يمكن لقيمة السمة name أن تحتوي على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. لا يمكن لهذه القيمة يتجاوز 255 حرفًا.

يمكنك، إذا أردت، استخدام العنصر <DisplayName> لتصنيف السياسة محرر الخادم الوكيل لواجهة مستخدم الإدارة باسم مختلف بلغة طبيعية.

لا ينطبق مطلوب
continueOnError

اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ سياسة. هذا متوقّع السلوك في معظم السياسات.

يمكنك ضبط القيمة على true لمواصلة تنفيذ المسار حتى بعد تطبيق إحدى السياسات. فشل.

خطأ اختياري
enabled

اضبط القيمة على true لفرض السياسة.

اضبط القيمة على false من أجل إيقاف السياسة. لن تكون السياسة ويتم فرضها حتى لو ظلت مرتبطة بتدفق.

صحيح اختياري
async

تم إيقاف هذه السمة نهائيًا.

خطأ منهي العمل به

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة name لتصنيف السياسة في إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>
تلقائي

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم ضبط قيمة السمة name للسياسة على النحو التالي: استخدام البيانات المختلفة.

التواجد في المنزل اختياري
النوع سلسلة

&lt;APIKey&gt; عنصر

يحدّد هذا العنصر متغيّر التدفق الذي يحتوي على مفتاح واجهة برمجة التطبيقات يرسل العميل عادةً مفتاح واجهة برمجة التطبيقات في معلَمة طلب بحث أو عنوان 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>

مواضيع ذات صلة