Règle AccessEntity

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône d'accès à la règle d'entité

Événement

Récupère les profils d'entité que vous spécifiez à partir du magasin de données Apigee. 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
  • 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.

Utilisez la règle AccessEntity pour obtenir les données de profil d'entité au format XML (ou JSON dans Apigee hybrid) et les placer dans une variable. Vous identifiez l'entité à obtenir en spécifiant un type d'entité et un ou plusieurs identifiants, qui indiquent quelle est l'entité de ce type que vous souhaitez obtenir. 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.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Accéder aux entités AppGroups à partir de AccessEntity

Vous pouvez également utiliser AccessEntity pour récupérer des entités AppGroup. Pour les entités associées, consultez la section Types d'entités et identifiants compatibles.

Pour en savoir plus sur les groupes d'applications et les fonctionnalités compatibles, consultez la page Utiliser les groupes d'applications pour organiser la propriété de l'application.

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é à obtenir auprès d'Apigee, ainsi que l'emplacement des 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 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>

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.

 N/A Obligatoire
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. Voir également :

 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

N/A

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 Requis 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 compatibles. 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>

É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 compatibles.

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 compatibles. Aucun Obligatoire Chaîne

Élément <OutputFormat>

Spécifie le format renvoyé par la règle AccessEntity : XML ou JSON.

<OutputFormat>XML</OutputFormat>
Par défaut

XML

Si vous omettez cet élément, la valeur par défaut est XML.
Présence Facultatif
Type Chaîne (XML ou JSON)

É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 Requis 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 compatibles. 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
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

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 Apigee pour obtenir le code XML de l'entité souhaitée. Pour en savoir plus, reportez-vous à la documentation de référence de l'API Apigee.

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

Applications

curl https://apigee.googleapis.com/v1/organizations/$ORG/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consultez également la page Obtenir une application par ID d'application dans la documentation de référence de l'API Apigee.

ou

$ curl https://apigee.googleapis.com/v1/organizations/$ORG/developers/$DEVELOPER_EMAIL/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consultez également la page Obtenir les détails des applications développeur dans la documentation de référence de l'API Apigee.

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 https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consultez également la page Obtenir le produit d'API dans la documentation de référence de l'API Apigee.

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>

Clé du site consommateur

curl https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL/apps/$APP/keys/$KEY \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consultez également la section Obtenir des informations sur la clé d'une application développeur dans la documentation de référence de l'API Apigee.

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 https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consultez également la page Obtenir un développeur dans la documentation de référence de l'API Apigee.

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 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 variable du nom de la variable.

Par exemple, si une règle AccessEntity portant le nom GetDeveloper est exécutée, le profil est stocké dans la variable nommée AccessEntity.GetDeveloper. Le profil 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] ND Le type d'entité utilisé doit correspondre à l'un des types acceptés.

Articles associés