AccessEntity ポリシー

概要

指定したエンティティのプロファイルを Apigee Edge データストアから取得します。このポリシーは、名前が AccessEntity.{policy_name} という形式の変数にプロファイルを格納します。AccessEntity を使用すると、以下のエンティティのプロファイルにアクセスできます。

アプリ
API プロダクト
会社
会社のデベロッパー
コンシューマキー
デベロッパー

AccessEntity ポリシーは、ポリシーベースのランタイムデータベース検索として機能します。このポリシーで返されたプロファイル情報を使用すると、条件付きのエンドポイントルーティング、フロー実行、ポリシー適用など、動的な動作を有効にできます。

AccessEntity ポリシーを使用して、エンティティのプロファイルデータを XML 形式で取得し、変数に格納します。取得するエンティティを指定するには、エンティティのタイプと ID を使用して、必要なタイプのエンティティを指定します。後で、別のポリシーを使用して、ExtractVariables ポリシーや AssignMessage ポリシーなどの別のポリシーのエンティティプロファイルデータを取得できます。

サンプル

以下のサンプルでは、ExtractVariables と AssignMessage ポリシーと一緒に 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.GetDeveloperProfile 変数から値を取得しています。この変数は AccessEntity で設定されています。

取得された値は 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="identifer_type"/>
  <SecondaryIdentifier ref="secondary_identifier" type="identifer_type"/>
</AccessEntity>

Identifiers 要素でエンティティをグループ化すると、同じタイプの複数のエンティティにアクセスできます。

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

<AccessEntity> 属性

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

次の表に、すべてのポリシーの親要素に共通する属性を示します。

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗した場合にエラーを返すには、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

<EntityIdentifier> 要素

取得するエンティティ（EntityType で指定されたタイプ）を指定します。

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

デフォルト	なし
要否	必須
型	文字列

属性

属性	説明	デフォルト	要否	型
ref	ID の参照元を格納する変数（例: `request.queryparam.apikey`）。	なし	必須。	文字列
type	ref 属性の変数で更新されるタイプ（例: `consumerkey`）。値の一覧については、エンティティタイプと ID をご覧ください。		必須。	文字列

例

<?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 要素を使用して、必要なタイプのエンティティを指定します。エンティティタイプのリファレンスについては、エンティティタイプと ID をご覧ください。

属性

属性	説明	デフォルト	要否	型
value	サポートされるエンティティタイプのいずれか。一覧については、エンティティタイプと ID をご覧ください。	なし	必須。	文字列

<SecondaryIdentifier> 要素

EntityIdentifier と一緒に使用して、EntityType の必要なインスタンスを表す値を指定します。

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

デフォルト	なし
要否	省略可
型	文字列

EntityIdentifier のみを指定しても単一エンティティの取得が保証されない場合は、SecondaryIdentifier を使用します。詳細については、セカンダリ ID での結果の絞り込みをご覧ください。

複数の SecondaryIdentifier 要素を使用することはできません。

属性

属性	説明	デフォルト	要否	型
ref	ID の参照元を格納する変数（例: `request.queryparam.apikey`）。	なし	必須。	文字列
type	ref 属性の変数で更新されるタイプ（例: `consumerkey`）。値の一覧については、エンティティタイプと ID をご覧ください。		必須。	文字列

例

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

使用上の注意

セカンダリ ID での結果の絞り込み

エンティティによっては、1 つの ID だけでは必要なエンティティが取得できないことがあります。この場合、セカンダリ ID を使用すると、結果を絞り込むことができます。

注: EntityIdentifier と SecondaryIdentifier の特定の組み合わせに一致する結果が複数ある場合、最初の一致がフローに適用されます。たとえば、アプリ ID を使用して API プロダクトのプロファイルを取得するとします。

最初のポリシー構成は次のようになります。

<?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 を使用します。たとえば、デフォルトでは、OAuth 2.0 による交換時に交換されるため、フローに appname 変数と 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="developer.app.name" type="appname"/>
    <SecondaryIdentifier ref="developer.id" type="developerid"/>
</AccessEntity>

サポートされるエンティティタイプと ID

AccessEntity は、次のエンティティタイプと ID をサポートします。

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 構造を理解しておく必要があります。構造のサンプルを確認するため、Management 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 プロダクトから 2 つ目の 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 ポリシーが実行されると、AccessEntity.GetDeveloper という名前の変数に XML 形式のプロファイルが格納されます。XML 形式のプロファイルは、ExtractVariables ポリシーに定義された XPath で解析されます。このポリシーでは、AccessEntity.GetDeveloper がソースとして指定されています。

エラーリファレンス

関連情報については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイムエラー

なし。

デプロイエラー

エラー名	障害文字列	HTTP ステータス	発生条件
`InvalidEntityType`	`Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name]`	なし	使用するエンティティタイプをサポートされているタイプのいずれかにする必要があります。

AccessEntity ポリシー

概要

サンプル

デベロッパーのメールアドレスを取得して他のポリシーで使用する

要素リファレンス

<AccessEntity> 属性

<DisplayName> 要素

<EntityIdentifier> 要素

属性

例

<EntityType> 要素

属性

<SecondaryIdentifier> 要素

属性

例

使用上の注意

セカンダリ ID での結果の絞り込み

サポートされるエンティティ タイプと ID

XML 形式のエンティティ プロファイルの例

アプリ

API プロダクト

会社

会社のデベロッパー

コンシューマ キー

デベロッパー

フロー変数

エラー リファレンス

ランタイム エラー

デプロイエラー

関連トピック

サポートされるエンティティタイプと ID

XML 形式のエンティティプロファイルの例

コンシューマキー

エラーリファレンス

ランタイムエラー