Правила AccessEntity

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Что

Извлекает из хранилища данных Apigee Edge профили объектов, которые вы укажете. Правило помещает профиль в переменную, название которой имеет формат AccessEntity.{policy_name}. С помощью AccessEntity можно получить доступ к профилям следующих организаций:

  • Для приложений
  • Продукт API
  • Компания
  • Разработчик компании
  • Пользовательский ключ
  • Разработчик

Правило AccessEntity работает как поиск в базе данных во время выполнения на основе правил. Вы можете использовать информацию профиля, возвращаемую этим правилом, чтобы включить динамическое поведение, например условную маршрутизацию конечных точек, выполнение потока или применение правил.

Вы можете использовать правило AccessEntity, чтобы получить данные профиля объекта в формате XML и поместить их в переменную. Чтобы определить, какой объект нужно получить, укажите его тип и один или несколько идентификаторов. Позже в другом правиле вы можете получить данные профиля объекта с помощью другого правила, например ExtractVariables или AssignMessage.

Примеры

В приведенных ниже примерах показано, как использовать AccessEntity вместе с правилами ExtractVariables и AssignMessage, чтобы извлечь адрес электронной почты разработчика и добавить его в заголовок HTTP.

Как получить адрес электронной почты разработчика для использования в других правилах

Настройте правило AccessEntity, чтобы указать, какой профиль объекта нужно получить из Edge, а также куда поместить данные профиля.

В следующем примере правила получают профиль объекта developer, используя ключ API, переданный в качестве параметра запроса для идентификации разработчика. Профиль помещается в переменную, название которой имеет вид 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

Этот атрибут устарел.

 ЛОЖЬ Устарело

Элемент <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, чтобы указать, какой объект заданного типа вам нужен. Справочник типов объектов можно найти в разделе Типы объектов и идентификаторы.

Атрибуты

Атрибут Описание По умолчанию Тип поля Тип
value Один из поддерживаемых типов объектов. Список приведен в разделе Типы объектов и идентификаторы. Нет. Обязательно. Строка

Элемент <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>

Поскольку приложение может быть связано с несколькими продуктами 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 для нужного объекта. Подробную информацию можно найти в справочнике по 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.

Альтернативный вариант:

$ 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

Также ознакомьтесь с разделом Получение продукта API в документации по API управления Edge.

Пример XPath, который извлекает второй ресурс API (URI) из продукта API с названием 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

Также ознакомьтесь с разделом Получение сведений о ключе для приложения разработчика в документации по API управления 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 в документации по API управления 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] Н/Д Используемый тип объекта должен быть одним из поддерживаемых типов .

Статьи по теме