AccessEntity 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

从 Apigee Edge 数据存储区中检索您指定的实体配置文件。该政策将配置文件放置在名称遵循 AccessEntity.{policy_name} 格式的变量中。您可以使用 AccessEntity 访问以下实体的配置文件:

  • 应用
  • API 产品
  • 公司
  • 公司开发者
  • 使用方密钥
  • 开发者

AccessEntity 政策充当基于政策的运行时数据库查询。您可以使用此政策返回的个人资料信息,以实现动态行为,例如条件端点路由、流执行、政策执行。

您可以使用 AccessEntity 政策获取实体个人资料数据作为 XML,并将其置于变量中。您可以通过指定实体类型以及指定所需类型实体的一个或多个标识符来标识实体。然后,在其他政策中,您可以使用另一政策检索实体配置文件数据,例如 ExtractVariables 政策AssignMessage 政策

示例

以下示例展示了与 ExtractVariablesAssignMessage 政策结合使用的 AccessEntity,用于提取开发者的电子邮件并将其添加到 HTTP 标头中。

获取用于其他政策的开发者电子邮件

设置 AccessEntity 政策,指定要从 Edge 获取哪个实体配置文件,以及配置文件数据的存储位置。

在以下示例中,该政策使用作为查询参数传递的 API 密钥标识开发者,以获取 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 之前设置的 AccessEntity.GetDeveloperProfile 变量中检索值。

请注意,检索的值在 XMLPayload 元素中被指定为 XPath 表达式。提取值放在 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,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

true 可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 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"/>

默认

不适用

状态

可选

类型

字符串

如果只指定 EntityIdentifier 无法保证您获得单个实体,请使用 SecondaryIdentifier。如需了解详情,请参阅使用辅助标识符缩小结果范围

不支持使用多个 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>

由于一个应用可与多个 API 产品关联,因此仅使用应用 ID 可能不会返回所需的 API 产品(您可以仅获取多个匹配产品中的第一个产品)。

如需获取更精确的结果,您可以改用 SecondaryIdentifier。例如,流中可能包含 appnamedeveloperid 变量,因为这些变量在 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 类型 SecondaryIdentifier 类型
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。如需了解详情,请参阅 Management API 参考文档

以下部分包含 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 Management API 参考文档中的按应用 ID 在组织中获取应用

或者:

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

API 产品

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

另请参阅 Edge Management API 参考文档中的获取 API 产品

XPath 示例,从名为 weather_free 的 API 产品中检索第二个 API 资源 (URI):

/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 Management API 参考文档中的 获取开发者应用的密钥详细信息

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 政策名称将设置为变量名称的变量前缀。

例如,如果执行名为 GetDeveloper 的 AccessEntity 政策,则 XML 格式的个人资料存储在名为 AccessEntity.GetDeveloper 的变量中。然后,可以使用在 ExtractVariables 政策中定义的 XPath 来解析 XML 格式的个人资料,ExtractVariables 政策指定 AccessEntity.GetDeveloper 作为其来源。

错误参考信息

如需了解相关信息,请参阅有关政策错误的注意事项处理故障

运行时错误

无。

部署错误

错误名称 故障字符串 HTTP 状态 发生的条件
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] 不适用 使用的实体类型必须是受支持的类型之一。

相关主题