AccessEntity ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

アクセスエンティティポリシーのアイコン

内容

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

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

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

AccessEntity ポリシーを使用して、エンティティのプロファイルデータを XML として（または Apigee ハイブリッドでは JSON として）取得し、変数に入力します。取得するエンティティを指定するには、エンティティタイプと ID を使用して、必要なタイプのエンティティを指定します。後で別のポリシーで、ExtractVariables ポリシーや AssignMessage ポリシーなどの別のポリシーを有するエンティティプロファイルデータを取得できます。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

`AccessEntity` から AppGroups エンティティにアクセスする

AccessEntity を使用して AppGroup エンティティを取得することもできます。関連するエンティティについては、サポートされるエンティティタイプと ID をご覧ください。

AppGroup とサポートされる機能については、AppGroups を使用したアプリのオーナー権限の編成をご覧ください。

例

以下の例では、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">

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

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	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`）。	該当なし	必須	文字列
タイプ	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>

<EntityType> 要素

データストアから取得するエンティティのタイプを指定します。

<EntityType  value="entity_type"/>

デフォルト	該当なし
プレゼンス	必須
種類	文字列

EntityIdentifier 要素を使用して、必要な特定のタイプのエンティティを指定します。エンティティタイプのリファレンスについては、サポートされるエンティティタイプと ID をご覧ください。

属性

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

<OutputFormat> 要素

注: <OutputFormat> は Hybrid v1.4 以降のハイブリッドでのみ使用できます。

AccessEntity ポリシーで返される形式を JSON または XML で指定します。

<OutputFormat>XML</OutputFormat>

デフォルト	XML この要素を省略した場合、値はデフォルトで XML になります。
プレゼンス	省略可
タイプ	文字列（XML または JSON）

デフォルト

XML

この要素を省略した場合、値はデフォルトで XML になります。

プレゼンス

省略可

タイプ

文字列（XML または JSON）

<SecondaryIdentifier> 要素

EntityIdentifier と一緒に使用して、指定された EntityType のインスタンスを特定する値を指定します。

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

デフォルト	該当なし
要否	省略可
タイプ	文字列

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

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

属性

属性	説明	デフォルト	要否	型
ref	ID の参照元を指定する変数（例: `request.queryparam.apikey`）。	該当なし	必須	文字列
タイプ	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 を使用できます。たとえば、フローに 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>

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

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

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 リファレンスの App 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 プロダクトから 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 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 という名前の変数にプロファイルが格納されます。そのプロファイルは、AccessEntity.GetDeveloper をソースとして指定する ExtractVariables ポリシーに定義された XPath を使用して解析できます。

エラーリファレンス

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.

AccessEntity ポリシー

内容

AccessEntity から AppGroups エンティティにアクセスする

例

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

要素リファレンス

<AccessEntity> 属性

<DisplayName> 要素

<EntityIdentifier> 要素

属性

例

<EntityType> 要素

属性

<OutputFormat> 要素

<SecondaryIdentifier> 要素

属性

例

使用上の注意

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

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

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

アプリ

API プロダクト

コンシューマ キー

デベロッパー

フロー変数

エラー リファレンス

Runtime errors

Deployment errors

関連トピック

`AccessEntity` から AppGroups エンティティにアクセスする

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

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

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

コンシューマキー

エラーリファレンス