سياسة AccessEntity

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

الأدوات المستخدمة

يجلب هذا الإجراء الملفات الشخصية للكيانات التي تحدّدها من مستودع بيانات Apigee Edge. تضع السياسة الملف الشخصي في متغيّر يتبع اسمه التنسيق AccessEntity.{policy_name}. يمكنك استخدام AccessEntity للوصول إلى الملفات الشخصية الخاصة بالجهات التالية:

  • التطبيق
  • منتج واجهة برمجة التطبيقات
  • الشركة
  • مطوّر الشركة
  • مفتاح العميل
  • المطوّر

تعمل سياسة AccessEntity كعملية بحث في قاعدة بيانات وقت التشغيل مستندة إلى السياسة. يمكنك استخدام معلومات الملف الشخصي التي تعرضها هذه السياسة لتفعيل سلوك ديناميكي، مثل توجيه نقاط النهاية الشرطي وتنفيذ التدفق وفرض السياسة.

يمكنك استخدام السياسة AccessEntity للحصول على بيانات ملف الكيان بتنسيق XML ووضعها في متغيّر. يمكنك تحديد الكيان المطلوب الحصول عليه من خلال تحديد نوع الكيان ومعرّف واحد أو أكثر يحدّد الكيان المطلوب من هذا النوع. في وقت لاحق، يمكنك استرداد بيانات ملف تعريف الكيان باستخدام سياسة أخرى، مثل سياسة ExtractVariables أو سياسة AssignMessage.

نماذج

تعرض الأمثلة التالية استخدام AccessEntity مع سياستَي ExtractVariables وAssignMessage لاستخراج عنوان البريد الإلكتروني الخاص بالمطوّر وإضافته إلى عنوان HTTP.

الحصول على عنوان البريد الإلكتروني للمطوّر لاستخدامه في سياسات أخرى

اضبط سياسة AccessEntity لتحديد ملف الجهة الذي سيتم الحصول عليه من Edge، بالإضافة إلى تحديد مكان وضع بيانات الملف.

في المثال التالي، تحصل السياسة على ملف شخصي خاص بالكيان developer، وذلك باستخدام مفتاح واجهة برمجة تطبيقات تم تمريره كمَعلمة طلب بحث لتحديد المطوّر. يتم وضع الملف الشخصي في متغير يتبع اسمه النموذج AccessEntity.{policy_name}. وبالتالي، سيكون المتغيّر الذي تحدّده هذه السياسة هو AccessEntity.GetDeveloperProfile.

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Edge datastore. -->
  <EntityType  value="developer"/>
  <!-- We tell the policy to use the API key (presented as query parameter) to identify the developer. -->
  <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/> 
</AccessEntity>

استخدِم سياسة أخرى لاسترداد قيمة الملف الشخصي للكيان من المتغيّر الذي تم ضبطه بواسطة AccessEntity.

في المثال التالي، تستردّ سياسة ExtractVariables قيمة من المتغيّر AccessEntity.GetDeveloperProfile الذي تم ضبطه سابقًا بواسطة AccessEntity.

يُرجى العِلم أنّ القيمة التي يتم استردادها يتم تحديدها كتعبير XPath في العنصر XMLPayload. يتم وضع القيمة المستخرَجة في المتغيّر developer.email.

<ExtractVariables name="SetDeveloperProfile">
  <!-- The source element points to the variable populated by AccessEntity policy. 
  The format is <policy-type>.<policy-name>.
  In this case, the variable contains the whole developer profile. -->
  <Source>AccessEntity.GetDeveloperProfile</Source> 
  <VariablePrefix>developer</VariablePrefix>
  <XMLPayload>
    <Variable name="email" type="string"> 
        <!-- You parse elements from the developer profile using XPath. -->
      <XPath>/Developer/Email</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>

تسترد سياسة AssignMessage التالية عنوان البريد الإلكتروني للمطوّر الذي تم ضبطه بواسطة سياسة ExtractVariables.

<!-- We'll use this policy to return the variables set in the developer profile, 
just so that we can easily see them in the response. -->
<AssignMessage name="EchoVariables">
  <AssignTo createNew="false" type="response"></AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="X-Developer-email">{developer.email}</Header>
    </Headers>
  </Set>
</AssignMessage>

مرجع العنصر

تتألف البنية الأساسية لسياسة AccessEntity مما يلي:

<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifier_type"/> 
  <SecondaryIdentifier ref="secondary_identifier" type="identifier_type"/>
</AccessEntity>

يمكنك الوصول إلى عناصر متعددة من النوع نفسه من خلال تجميعها في عنصر Identifiers:

<AccessEntity name="name_of_the_policy">
  <EntityType  value="type_of_entity"/>
  <Identifiers>
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
  </Identifiers>
</AccessEntity>

سمات <AccessEntity>

<AccessEntity async="false" continueOnError="false" enabled="true" name="policy_name">

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

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

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

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

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

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

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

 خطأ اختياري
enabled

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

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

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

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

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

&lt;DisplayName&gt; عنصر

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

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

لا ينطبق

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

عنصر <EntityIdentifier>

تحدّد الكيان المعيّن المطلوب الحصول عليه، وهو من النوع المحدّد في EntityType.

<EntityIdentifier ref="value_variable" type="identifier_type"/>

تلقائي

لا ينطبق

التواجد

مطلوب

النوع

سلسلة

السمات

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

المتغيّر الذي يوفّر مصدر المعرّف، مثل request.queryparam.apikey

 لا ينطبق الحقل مطلوب. سلسلة
النوع النوع الذي يتم ملؤه بواسطة المتغير في السمة ref، مثل consumerkey. اطّلِع على أنواع الكيانات ومعرّفاتها للحصول على قائمة بالقيم. الحقل مطلوب. سلسلة

مثال

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetCompany">
    <DisplayName>GetCompanyProfile</DisplayName>
    <EntityType value="company"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>

عنصر <EntityType>

تحدّد هذه السمة نوع العنصر الذي سيتم استرداده من مستودع البيانات.

<EntityType  value="entity_type"/>

تلقائي

لا ينطبق

التواجد

مطلوب

النوع

سلسلة

استخدِم عنصر EntityIdentifier لتحديد الكيان المطلوب من النوع المحدّد. للحصول على مرجع لأنواع الكيانات، يُرجى الاطّلاع على أنواع الكيانات ومعرّفاتها.

السمات

السمة الوصف تلقائي التواجد في المنزل النوع
القيمة أحد أنواع العناصر المتوافقة يمكنك الاطّلاع على أنواع الكيانات والمعرّفات للحصول على قائمة. بلا عُري الحقل مطلوب. سلسلة

العنصر <SecondaryIdentifier>

بالإضافة إلى EntityIdentifier، تحدّد هذه السمة قيمة لتعريف مثيل EntityType المطلوب.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>

تلقائي

لا ينطبق

التواجد

اختياري

النوع

سلسلة

استخدِم SecondaryIdentifier عند تحديد EntityIdentifier فقط، لأنّ ذلك لن يضمن لك الحصول على كيان واحد. يمكنك الاطّلاع على تضييق نطاق النتائج باستخدام المعرّفات الثانوية لمزيد من المعلومات.

لا يمكن استخدام عناصر SecondaryIdentifier متعددة.

السمات

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

المتغيّر الذي يوفّر مصدر المعرّف، مثل request.queryparam.apikey

 لا ينطبق الحقل مطلوب. سلسلة
النوع النوع الذي يتم ملؤه بواسطة المتغير في السمة ref، مثل consumerkey. اطّلِع على أنواع الكيانات ومعرّفاتها للحصول على قائمة بالقيم. الحقل مطلوب. سلسلة

مثال

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetAPIProduct">
    <DisplayName>GetAPIProduct</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>

ملاحظات الاستخدام

تضييق نطاق النتائج باستخدام معرّفات ثانوية

بالنسبة إلى بعض الكيانات، قد لا يكون تقديم معرّف واحد محدّدًا بما يكفي للحصول على الكيان الذي تريده. في هذه الحالات، يمكنك استخدام معرّف ثانوي لتضييق نطاق النتائج.

قد تبدو إعدادات السياسة الأولى، التي قد تكون واسعة النطاق، على النحو التالي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>

بما أنّ التطبيق يمكن ربطه بمنتجات متعددة من واجهات برمجة التطبيقات، قد لا يؤدي استخدام معرّف التطبيق وحده إلى عرض منتج واجهة برمجة التطبيقات الذي تريده (قد يظهر لك المنتج الأول فقط من بين عدة منتجات مطابقة).

بدلاً من ذلك، للحصول على نتيجة أكثر دقة، يمكنك استخدام SecondaryIdentifier. على سبيل المثال، قد تتضمّن عملية الربط المتغيّرين appname وdeveloperid لأنّه يتم ملؤهما تلقائيًا أثناء عملية تبادل OAuth 2.0. يمكنك استخدام قيم هذه المتغيّرات في سياسة AccessEntity للحصول على تفاصيل الملف الشخصي في التطبيق الذي يرسل الطلب.

قد تبدو إعدادات السياسة الأكثر تحديدًا على النحو التالي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>

أنواع الكيانات والمعرّفات المتوافقة

تتيح AccessEntity أنواع الكيانات والمعرّفات التالية.

قيمة EntityType EntityIdentifier Types SecondaryIdentifier Types
apiproduct appid apiresource
apiproductname
appname apiresource
developeremail
developerid
companyname
consumerkey apiresource
app appid
appname developeremail
developerid
companyname
consumerkey
authorizationcode authorizationcode
company appid
company
consumerkey
companydeveloper companyname
consumerkey consumerkey
consumerkey_scope consumerkey
developer appid
consumerkey
developeremail
developerid
requesttoken requesttoken consumerkey
verifier verifier

مثال على ملف XML الخاص بملف كيان

لاسترداد قيمة ملف بيانات الكيان الذي تريده باستخدام XPath، عليك معرفة بعض المعلومات حول بنية ملف XML الخاص بملف البيانات. للحصول على مثال على البنية، استخدِم طلب بيانات من واجهة برمجة تطبيقات الإدارة للحصول على تنسيق XML للكيان الذي تريده. لمعرفة التفاصيل، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات الإدارية.

تتضمّن الأقسام التالية رمزًا لطلبات البيانات من واجهة برمجة التطبيقات، بالإضافة إلى مثال على XML من الطلب.

التطبيقات

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password

راجِع أيضًا الحصول على تطبيق في مؤسسة حسب رقم تعريف التطبيق في مرجع واجهة برمجة تطبيقات إدارة Edge.

أو:

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u email:password

راجِع أيضًا الحصول على تفاصيل تطبيق المطوّر في مرجع واجهة برمجة التطبيقات لإدارة Edge.

نموذج الملف الشخصي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<App name="thomas-app">
    <AccessType>read</AccessType>
    <ApiProducts/>
    <Credentials>
        <Credential>
            <Attributes/>
            <ConsumerKey>wrqOOOiPArFI0WRoB1gAJMRbOguekJ5w</ConsumerKey>
            <ConsumerSecret>WvOhDrJ8m6kzz7Ni</ConsumerSecret>
            <ApiProducts>
                <ApiProduct>
                    <Name>FreeProduct</Name>
                    <Status>approved</Status>
                </ApiProduct>
            </ApiProducts>
            <Scopes/>
            <Status>approved</Status>
        </Credential>
    </Credentials>
    <AppFamily>default</AppFamily>
    <AppId>ab308c13-bc99-4c50-8434-0e0ed1b86075</AppId>
    <Attributes>
        <Attribute>
            <Name>DisplayName</Name>
            <Value>Tom's Weather App</Value>
        </Attribute>
    </Attributes>
    <CallbackUrl>http://tom.app/login</CallbackUrl>
    <CreatedAt>1362502872727</CreatedAt>
    <CreatedBy>admin@apigee.com</CreatedBy>
    <DeveloperId>PFK8IwOeAOW01JKA</DeveloperId>
    <LastModifiedAt>1362502872727</LastModifiedAt>
    <LastModifiedBy>admin@apigee.com</LastModifiedBy>
    <Scopes/>
    <Status>approved</Status>
</App>

منتج واجهة برمجة التطبيقات

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

راجِع أيضًا Get API Product في مرجع واجهة برمجة التطبيقات لإدارة Edge.

نموذج XPath، يسترد مورد واجهة برمجة التطبيقات الثاني (URI) من منتج واجهة برمجة التطبيقات المسمى weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

نموذج ملف شخصي معروض بتنسيق XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>

الشركة

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password

اطّلِع أيضًا على الحصول على تفاصيل الشركة في مرجع Edge Management API.

نموذج الملف الشخصي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>

مطوّر الشركة

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u email:password

نموذج الملف الشخصي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

مفتاح العميل

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u email:password

يمكنك أيضًا الاطّلاع على الحصول على تفاصيل المفتاح لتطبيق مطوِّر في مرجع واجهة برمجة التطبيقات لإدارة Edge.

نموذج XPath:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

نموذج الملف الشخصي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>

المطوّر

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

راجِع أيضًا Get Developer في مرجع واجهة برمجة التطبيقات الخاصة بإدارة Edge.

نموذج XPath:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
 
/Developer/Email/text()

نموذج الملف الشخصي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>

متغيّرات سير العمل

عند استرداد ملف تعريف الكيان المحدّد في سياسة AccessEntity، تتم إضافة عنصر ملف التعريف المنسّق بتنسيق XML إلى سياق الرسالة كمتغيّر. ويمكن الوصول إليه مثل أي متغير آخر، وذلك بالإشارة إلى اسم المتغير. يتم ضبط الاسم الذي يقدّمه المستخدم لسياسة AccessEntity كبادئة متغيرة لاسم المتغير.

على سبيل المثال، إذا تم تنفيذ سياسة AccessEntity باسم GetDeveloper، سيتم تخزين الملف الشخصي بتنسيق XML في المتغيّر المسمّى AccessEntity.GetDeveloper. يمكن بعد ذلك تحليل الملف الشخصي المنسّق بتنسيق XML باستخدام تعبير XPath محدّد في سياسة ExtractVariables يحدّد AccessEntity.GetDeveloper كمصدر له.

مرجع الخطأ

للحصول على معلومات ذات صلة، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.

أخطاء في وقت التشغيل

بلا عُري

أخطاء النشر

اسم الخطأ سلسلة الخطأ رموز حالة HTTP يحدث عند
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] لا ينطبق يجب أن يكون نوع الكيان المستخدَم من الأنواع المتوافقة.

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