AccessEntity ポリシー

概要

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

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

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

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

サンプル

以下のサンプルでは、ExtractVariablesAssignMessage ポリシーと一緒に 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> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

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

なし

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

要否: 省略可
型: 文字列

<EntityIdentifier> 要素

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

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

デフォルト

なし

要否

必須

String

属性

属性 説明 デフォルト 要否
ref

ID の参照元を格納する変数(例: request.queryparam.apikey)。

なし 必須。 String
type ref 属性の変数で更新されるタイプ(例: consumerkey)。値の一覧については、エンティティ タイプと ID をご覧ください。 必須。 String

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

デフォルト

なし

要否

必須

String

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

属性

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

<SecondaryIdentifier> 要素

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

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

デフォルト

なし

要否

省略可

String

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

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

属性

属性 説明 デフォルト 要否
ref

ID の参照元を格納する変数(例: request.queryparam.apikey)。

なし 必須。 String
type ref 属性の変数で更新されるタイプ(例: consumerkey)。値の一覧については、エンティティ タイプと ID をご覧ください。 必須。 String

    <?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
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 を取得します。詳細については、管理 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 管理 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 管理 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 管理 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 管理 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 管理 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 管理 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] なし 使用するエンティティ タイプがサポート対象のタイプではありません。

関連トピック