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.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="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 に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの 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> 要素

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

<OutputFormat>XML</OutputFormat>
デフォルト

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 を使用すると、結果を絞り込むことができます。

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

<?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
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 を使用して解析できます。

エラー リファレンス

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

ランタイム エラー

なし。

デプロイエラー

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

関連トピック