AccessEntity 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

访问实体政策图标

内容

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

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

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

使用 AccessEntity 政策获取实体配置文件数据作为 XML（在 Apigee Hybrid 中为 JSON），并将其置于变量中。指定实体类型以及指定所需类型实体的一个或多个标识符，以标识要获取的实体。然后，在其他政策中，您可以使用另一政策检索实体配置文件数据，例如 ExtractVariables 政策或 AssignMessage 政策。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

从 AccessEntity 访问 AppGroups 实体

您还可以使用 AccessEntity 检索 AppGroup 实体。请参阅支持的实体类型和标识符，以查看相关实体。

如需了解 AppGroup 和支持的功能，请参阅使用 AppGroup 整理应用所有权。

示例

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

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

设置 AccessEntity 政策以指定从 Apigee 获取的实体配置文件，以及放置配置文件数据的位置。

在以下示例中，该政策使用作为查询参数传递的 API 密钥标识开发者，以获取 developer 实体配置文件。配置文件会放置在名称遵循 AccessEntity.{policy_name} 格式的变量中。因此，此政策设置的变量为 AccessEntity.GetDeveloperProfile。

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Apigee 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">

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 Presence
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：

 false 可选
enabled

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

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

 true 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

用于在 name 属性之外在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
Presence 可选
类型 字符串

<EntityIdentifier> 元素

指定要获取的特定实体（具有 EntityType 中指定的类型）。

<EntityIdentifier ref="value_variable" type="identifier_type"/>
默认 不适用
Presence 必需
类型 字符串

属性

属性 说明 默认 Presence 类型
ref

提供标识符的来源的变量，例如 request.queryparam.apikey。

 不适用 必需 字符串
type 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>

<EntityType> 元素

指定要从数据存储区中检索的实体类型。

<EntityType  value="entity_type"/>
默认 不适用
Presence 必需
类型 字符串

使用 EntityIdentifier 元素指定所需的给定类型的实体。如需了解实体类型，请参阅支持的实体类型和标识符。

属性

属性 说明 默认 Presence 类型
值 支持的实体类型之一。请参阅支持的实体类型和标识符，以查看列表。 无 必需 字符串

<OutputFormat> 元素

指定 AccessEntity 政策返回的格式：XML 或 JSON。

<OutputFormat>XML</OutputFormat>
默认

XML

如果您省略此元素，则该值默认为 XML。
Presence 可选
类型 字符串（XML 或 JSON）

<SecondaryIdentifier> 元素

结合 EntityIdentifier 指定一个值，以标识给定 EntityType 的所需实例。

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
默认 不适用
Presence 可选
类型 字符串

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

不支持使用多个 SecondaryIdentifier 元素。

属性

属性 说明 默认 Presence 类型
ref

提供标识符的来源的变量，例如 request.queryparam.apikey。

 不适用 必需 字符串
type 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。例如，流中可能包含 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 类型 SecondaryIdentifier 类型
apiproduct appid apiresource
apiproductname
appname apiresource
developeremail
developerid
appgroupname
consumerkey apiresource
app appid
appname developeremail
developerid
appgroupname
consumerkey
authorizationcode authorizationcode
appgroupname appid
appgroupname
consumerkey
consumerkey
consumerkey consumerkey
consumerkey_scope consumerkey
developer appid
consumerkey
developeremail
developerid
requesttoken requesttoken consumerkey
verifier verifier

实体配置文件 XML 示例

要使用 XPath 检索所需的实体配置文件值，您需要了解有关配置文件 XML 结构的一些情况。如需查看结构示例，请使用 Apigee API 调用为所需实体获取 XML。如需了解详情，请参阅 Apigee API 参考文档。

以下部分包含 API 调用的代码以及该调用中的 XML 示例。

应用

curl https://apigee.googleapis.com/v1/organizations/$ORG/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

另请参阅 Apigee API 参考文档中的按应用 ID 获取应用。

或：

$ curl https://apigee.googleapis.com/v1/organizations/$ORG/developers/$DEVELOPER_EMAIL/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

另请参阅 Apigee 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 https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

另请参阅 Apigee 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 https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL/apps/$APP/keys/$KEY \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

另请参阅 Apigee 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 https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

另请参阅 Apigee 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 政策中指定的实体配置文件时，配置文件对象将作为变量添加到消息上下文中。其访问方式与任何其他变量相同，并引用变量名称。用户提供的 AccessEntity 政策名称设置为变量名称的变量前缀。

例如，如果执行名为 GetDeveloper 的 AccessEntity 政策，则配置文件存储在名为 AccessEntity.GetDeveloper 的变量中。然后，可以使用在 ExtractVariables 政策中定义的 XPath 来解析配置文件，ExtractVariables 政策指定 AccessEntity.GetDeveloper 作为其来源。

错误参考信息

For related information, see What you need to know about policy errors and Handling faults.

Runtime errors

None.

Deployment errors

Error name Fault string HTTP status Occurs when
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A The entity type used must be one of the supported types.

相关主题