Règle AccessEntity

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

Quoi

Récupère les profils d'entités que vous spécifiez à partir du datastore Apigee Edge. La règle place le profil dans une variable dont le nom suit le format AccessEntity.{policy_name}. Vous pouvez utiliser AccessEntity pour accéder aux profils des entités suivantes :

  • Application
  • Produit d'API
  • Société
  • Développeur d'entreprise
  • Clé du site consommateur
  • Développeur

La règle AccessEntity fonctionne comme une recherche dans la base de données d'exécution basée sur des règles. Vous pouvez utiliser les informations de profil renvoyées par cette règle pour activer le comportement dynamique, tel que le routage de point de terminaison conditionnel, l'exécution de flux et l'application des règles.

Vous utilisez la règle AccessEntity pour obtenir les données de profil d'entité en tant que XML et les placer dans une variable. Vous identifiez l'entité à obtenir en spécifiant un type d'entité et un ou plusieurs identifiants qui spécifient l'entité de ce type souhaitée. Plus tard, dans une autre règle, vous pourrez récupérer les données de profil d'entité avec une autre règle, telle qu'une règle ExtractVariables ou AssignMessage.

Exemples

Les exemples suivants montrent AccessEntity utilisé conjointement avec les règles ExtractVariables et AssignMessage pour extraire l'e-mail d'un développeur et l'ajouter à l'en-tête HTTP.

Obtenir l'adresse e-mail d'un développeur pour l'utiliser dans d'autres règles

Configurer la règle AccessEntity pour spécifier le profil d'entité à partir duquel les données doivent être récupérées Edge et indique où placer les données de profil.

Dans l'exemple suivant, la règle obtient un profil d'entité developer à l'aide d'une clé API transmise en tant que paramètre de requête pour identifier le développeur. Le profil est placé dans une variable dont le nom suit le format AccessEntity.{policy_name}. La variable définie par cette règle est donc 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>

Utiliser une autre règle pour extraire la valeur du profil d'entité de la variable définie par AccessEntity.

Dans l'exemple suivant, une règle ExtractVariables récupère une valeur de la variable AccessEntity.GetDeveloperProfile précédemment définie par AccessEntity.

Notez que la valeur extraite est spécifiée en tant qu'expression XPath dans l'élément XMLPayload. La valeur extraite est placée dans une variable 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>

La règle AssignMessage suivante récupère l'adresse e-mail du développeur définie par la règle 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>

Documentation de référence des éléments

La structure de base d'une règle AccessEntity est la suivante :

<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifier_type"/> 
  <SecondaryIdentifier ref="secondary_identifier" type="identifier_type"/>
</AccessEntity>

Vous pouvez accéder à plusieurs entités du même type en les regroupant dans un élément 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>

Attributs <AccessEntity>

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut Description Par défaut Présence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

ND Valeur
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle.

faux Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

vrai Facultatif
async

Cet attribut est obsolète.

faux Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>
Par défaut

ND

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Présence Facultatif
Type Chaîne

Élément <EntityIdentifier>

Spécifie l'entité spécifique (du type indiqué dans EntityType) à obtenir.

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

Par défaut

N/A

Présence

Requis

Type

Chaîne

Attributs

Attribut Description Par défaut Présence Type
ref

Variable qui fournit la source de l'identifiant, telle que request.queryparam.apikey.

ND Obligatoire. Chaîne
type Type renseigné par la variable dans l'attribut "ref", tel que consumerkey. Pour obtenir la liste des valeurs, consultez la section Types d'entités et identifiants. Obligatoire. Chaîne

Exemple

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

Élément <EntityType>

Spécifie le type d'entité à récupérer à partir du magasin de données.

<EntityType  value="entity_type"/>

Par défaut

N/A

Présence

Requis

Type

Chaîne

Utilisez un élément EntityIdentifier pour spécifier l'entité du type que vous souhaitez. Pour en savoir plus sur les types d'entités, consultez la section Types d'entités et identifiants.

Attributs

Attribut Description Par défaut Présence Type
value L'un des types d'entité acceptés. Pour en obtenir la liste, consultez la section Types d'entités et identifiants. Aucune Obligatoire. Chaîne

Élément <SecondaryIdentifier>

Conjointement avec EntityIdentifier, spécifie une valeur permettant d'identifier l'instance souhaitée pour l'élément EntityType donné.

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

Par défaut

N/A

Présence

Facultatif

Type

Chaîne

L'utilisation de SecondaryIdentifier lorsque vous ne spécifiez qu'un élément EntityIdentifier ne garantit pas l'obtention d'une seule entité. Pour en savoir plus, consultez la section Affiner les résultats avec des identifiants secondaires.

L'utilisation de plusieurs éléments SecondaryIdentifier n'est pas acceptée.

Attributs

Attribut Description Par défaut Présence Type
ref

Variable qui fournit la source de l'identifiant, telle que request.queryparam.apikey.

ND Obligatoire. Chaîne
type Type renseigné par la variable dans l'attribut "ref", tel que consumerkey. Pour obtenir la liste des valeurs, consultez la section Types d'entités et identifiants. Obligatoire. Chaîne

Exemple

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

Remarques sur l'utilisation

Affiner les résultats avec des identifiants secondaires

Pour certaines entités, la spécification d'un seul identifiant peut ne pas être assez spécifique pour obtenir l'entité de votre choix. Dans ce cas, vous pouvez utiliser un identifiant secondaire pour affiner les résultats.

La configuration initiale des règles peut ressembler à ceci :

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

Étant donné qu'une application peut être associée à plusieurs produits d'API, l'utilisation de l'ID de l'application peut ne pas renvoyer le produit d'API souhaité (vous pouvez n'obtenir que le premier de plusieurs produits correspondants).

Pour obtenir un résultat plus précis, vous pouvez utiliser un élément SecondaryIdentifier. Par exemple, vous pouvez inclure des variables appname et developerid dans le flux, car elles sont renseignées par défaut lors d'un échange OAuth 2.0. Vous pouvez utiliser les valeurs de ces variables dans une règle AccessEntity pour obtenir des détails de profil sur l'application à l'origine de la requête.

La configuration des règles plus spécifique peut ressembler à ceci :

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

Types d'entités et identifiants compatibles

AccessEntity accepte les types d'entités et les identifiants suivants.

Valeur EntityType Types EntityIdentifier Types 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

Exemple de profil d'entité au format XML

Pour récupérer la valeur du profil d'entité que vous souhaitez avec XPath, vous devez connaître la structure XML du profil. Pour obtenir un exemple de structure, utilisez un appel d'API de gestion pour obtenir XML pour l'entité de votre choix. Pour plus d'informations, reportez-vous à la documentation sur l'API de gestion référence.

Les sections suivantes incluent du code pour les appels d'API ainsi qu'un exemple de code XML provenant de l'appel.

Applications

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password

Consultez également l'article Télécharger l'application dans Organisation par ID d'application dans la documentation de référence de l'API de gestion Edge.

soit :

$ 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

Consultez également la section Obtenir Détails de l'application du développeur dans la documentation de référence de l'API de gestion Edge.

Exemple de profil :

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

Produit d'API

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

Voir aussi Obtenir l'API Produit dans la documentation de référence de l'API de gestion Edge.

L'exemple XPath récupère la deuxième ressource API (URI) du produit d'API nommé weather_free :

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

Exemple de profil renvoyé au format 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>

Entreprise

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password

Consultez également la section Obtenir Informations sur l'entreprise dans la documentation de référence de l'API de gestion Edge.

Exemple de profil :

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

Développeur d'entreprise

$ 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

Exemple de profil :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

Clé du site consommateur

$ 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

Voir aussi Obtenez des informations clés pour une application de développeur dans la documentation de référence de l'API de gestion Edge.

Exemple XPath :

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

Exemple de profil :

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

Développeur

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

Consultez également la section Obtenir le rôle de développeur dans la documentation de référence de l'API de gestion Edge.

Exemple XPath :

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
/Developer/Email/text()

Exemple de profil :

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

Variables de flux

Lorsque le profil d'entité spécifié dans la règle AccessEntity est récupéré, l'objet de profil au format XML est ajouté au contexte du message en tant que variable. Il est accessible comme n'importe quelle autre variable, en faisant référence au nom de la variable. Le nom fourni par l'utilisateur de la règle AccessEntity est défini comme préfixe du nom de la variable.

Par exemple, si une règle AccessEntity associée au nom GetDeveloper est exécutée, le profil au format XML est stocké dans la variable nommée AccessEntity.GetDeveloper. Le profil au format XML peut ensuite être analysé à l'aide d'un XPath défini dans une règle ExtractVariables spécifiant AccessEntity.GetDeveloper comme source.

Informations de référence sur les erreurs

Pour en savoir plus, consultez les articles Ce que vous devez savoir sur les erreurs liées aux règles et la gestion des erreurs.

Erreurs d'exécution

Aucune

Erreurs de déploiement

Nom de l'erreur Chaîne d'erreur État HTTP Se produit quand
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A Le type d'entité utilisé doit correspondre à l'un des types acceptés.

Articles associés