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. Consultez la section Types d'entités et identifiants compatibles pour obtenir des informations sur les entités associées.

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	Presence
`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 : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	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.	true	Facultatif
`async`	Cet attribut est obsolète.	false	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

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut `name` de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

N/A

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

Presence 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
Presence	Obligatoire
Type	Chaîne

Attributs

Attribut	Description	Par défaut	Presence	Type
ref	Variable qui fournit la source de l'identifiant, telle que `request.queryparam.apikey`.	N/A	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 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
Presence	Obligatoire
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	Presence	Type
valeur	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>

Remarque : <OutputFormat> n'est disponible que dans les environnements hybrides, à partir de la version 1.4 hybride.

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.
Presence	Facultatif
Type	Chaîne (XML ou JSON)

Par défaut

XML

Si vous omettez cet élément, la valeur par défaut est XML.

Presence

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
Presence	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	Presence	Type
ref	Variable qui fournit la source de l'identifiant, telle que `request.queryparam.apikey`.	N/A	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 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.

Remarque : Lorsque plusieurs correspondances existent pour une combinaison EntityIdentifier et SecondaryIdentifier donnée, la première correspondance est renseignée dans le flux. Par exemple, considérons un cas où vous souhaitez obtenir un profil de produit d'API à l'aide d'un ID d'application.

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.

$ 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

ExtractVariables : Règle ExtractVariables
AssignMessage : Règle AssignMessage

Règle AccessEntity

Événement

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

Exemples

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

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

Attributs <AccessEntity>

Élément <DisplayName>

Élément <EntityIdentifier>

Attributs

Exemple

Élément <EntityType>

Attributs

Élément <OutputFormat>

Élément <SecondaryIdentifier>

Attributs

Exemple

Remarques sur l'utilisation

Affiner les résultats avec des identifiants secondaires

Types d'entités et identifiants compatibles

Exemple de profil d'entité au format XML

Applications

Produit d'API

Clé du site consommateur

Développeur

Variables de flux

Informations de référence sur les erreurs

Erreurs d'exécution

Erreurs de déploiement

Articles associés

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