AccessEntity ポリシー

このページの内容は ApigeeApigee ハイブリッドに該当します。

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

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 を使用できます。たとえば、フローに 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 を使用して解析できます。

エラー リファレンス

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

ランタイム エラー

なし。

デプロイエラー

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

関連トピック