خط‌مشی AccessEntity

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

چه

نمایه‌های نهادی را که مشخص کرده‌اید از مخزن داده Apigee Edge بازیابی می‌کند. این خط‌مشی نمایه را در متغیری قرار می‌دهد که نام آن از قالب AccessEntity.{policy_name} پیروی می‌کند. می‌توانید از AccessEntity برای دسترسی به نمایه‌های نهادهای زیر استفاده کنید:

  • برنامه
  • محصول میانای برنامه‌سازی کاربردی
  • شرکت
  • توسعه‌دهنده شرکت
  • کلید مصرف‌کننده
  • توسعه‌دهنده

خط‌مشی AccessEntity به‌عنوان جستجوی پایگاه داده زمان اجرای مبتنی بر خط‌مشی عمل می‌کند. می‌توانید از اطلاعات نمایه‌ای که این خط‌مشی برمی‌گرداند برای فعال کردن رفتار پویا، مثل مسیریابی نقطه پایانی شرطی، اجرای جریان، و اجرای خط‌مشی استفاده کنید.

از خط‌مشی AccessEntity برای دریافت داده‌های نمایه نهاد به‌صورت XML و قرار دادن آن در متغیر استفاده می‌کنید. با مشخص کردن نوع نهاد و یک یا چند شناسه که مشخص می‌کنند کدام نهاد از آن نوع را می‌خواهید، نهاد موردنظرتان را برای دریافت شناسایی می‌کنید. بعداً، در خط‌مشی دیگری، می‌توانید داده‌های نمایه نهاد را با خط‌مشی دیگری، مثل خط‌مشی ExtractVariables policy یا AssignMessage policy، بازیابی کنید.

نمونه‌ها

نمونه‌های زیر نشان می‌دهد که 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> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

 N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

 نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

 درست است اختیاری
async

این ویژگی منسوخ شده است.

 نادرست منسوخ شده است

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <EntityIdentifier>

نهاد خاصی را که از نوع ارائه‌شده در EntityType است مشخص می‌کند تا دریافت شود.

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

پیش‌فرض

موجود نیست

حضور

الزامی

تایپ کردن

رشته

مشخصه‌ها

مشخصه شرح پیش‌فرض حضور نوع
مرجع

متغیری که منبع شناسه را ارائه می‌دهد، مانند 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"/>

پیش‌فرض

موجود نیست

حضور

اختیاری

تایپ کردن

رشته

هنگام مشخص کردن فقط یک EntityIdentifier از SecondaryIdentifier استفاده کنید این کار تضمین نمی‌کند که یک نهاد واحد دریافت کنید. برای اطلاعات بیشتر، محدود کردن نتایج با شناسه‌های ثانویه را ببینید.

استفاده از چند عنصر SecondaryIdentifier پشتیبانی نمی‌شود.

مشخصه‌ها

مشخصه شرح پیش‌فرض حضور نوع
مرجع

متغیری که منبع شناسه را ارائه می‌دهد، مانند 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>

ازآنجایی‌که یک برنامه می‌تواند با چندین محصول API مرتبط باشد، استفاده از شناسه برنامه به‌تنهایی ممکن است محصول API موردنظر شما را برنگرداند (ممکن است فقط اولین محصول از چندین محصول منطبق را دریافت کنید).

درعوض، برای دریافت نتیجه دقیق‌تر، می‌توانید از 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 انواع شناسه ثانویه
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 نمایه اطلاعاتی داشته باشید. برای نمونه‌ای از ساختار، از فراخوانی API مدیریت برای دریافت XML برای نهادی که می‌خواهید استفاده کنید. برای جزئیات، به مرجع میانای برنامه‌سازی کاربردی مدیریت مراجعه کنید.

بخش‌های زیر شامل کد برای تماس‌های API، همراه با نمونه 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 management API ببینید.

نمایه نمونه:

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

همچنین دریافت میانای برنامه‌سازی کاربردی محصول را در مرجع میانای برنامه‌سازی کاربردی مدیریت Edge ببینید.

نمونه XPath، دومین منبع API (نشانی وب) را از محصول API با نام weather_free بازیابی می‌کند:

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

نمایه نمونه به‌عنوان زبان نشانه‌گذاری توسعه‌پذیر برگردانده شد:

<?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» ببینید.

نمایه نمونه:

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

همچنین دریافت توسعه‌دهنده را در مرجع Edge management API ببینید.

نمونه 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] N/A نوع موجودیت مورد استفاده باید یکی از انواع پشتیبانی شده باشد.

موضوعات مرتبط