سياسة VerificationAPIKey

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

المزايا

تتيح لك سياسة "مفتاح واجهة برمجة التطبيقات" (Verify API Key) فرض التحقُّق من مفاتيح واجهة برمجة التطبيقات في وقت التشغيل، مع السماح فقط التطبيقات التي تمتلك مفاتيح واجهة برمجة تطبيقات معتمدة يمكنها الوصول إلى واجهات برمجة التطبيقات. تضمن هذه السياسة أن تكون مفاتيح واجهة برمجة التطبيقات صالحة، وأن تتضمّن لم يتم إبطالها، وتمت الموافقة على استهلاكها للموارد المحددة المرتبطة بواجهة برمجة التطبيقات المنتجات.

نماذج

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

<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>

verifyapikey.{policy_name}

لمحة عن سياسة "مفتاح واجهة برمجة التطبيقات" (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">

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

<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

وتشمل المتغيرات المتاحة ما يلي:

متغيّرات مسار التطبيق

تتم تعبئة متغيّرات التدفق التالية التي تحتوي على معلومات عن التطبيق من خلال السياسة. يسبق كل هذه المتغيرات:

verifyapikey.{policy_name}.app.

على سبيل المثال:

verifyapikey.{policy_name}.app.name

وتشمل المتغيرات المتاحة ما يلي:

متغيّرات مسار المطوِّر

تتم تعبئة متغيرات التدفق التالية التي تحتوي على معلومات حول المطور بواسطة . يسبق كل هذه المتغيرات:

verifyapikey.{policy_name}.developer

على سبيل المثال:

verifyapikey.{policy_name}.developer.id

وتشمل المتغيرات المتاحة ما يلي:

متغيرات تدفق الشركة

تتم تعبئة متغيرات التدفق التالية التي تحتوي على معلومات حول الشركة . يسبق كل هذه المتغيرات:

verifyapikey.{policy_name}.company

على سبيل المثال:

verifyapikey.{policy_name}.company.name

وتشمل المتغيرات المتاحة ما يلي:

المتغيّرات في "إحصاءات 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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

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>

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