Política de AccessEntity

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

icono de política de entidad de acceso

Qué

Recupera los perfiles de entidad que especifiques del almacén de datos de Apigee. La política coloca el perfil en una variable cuyo nombre sigue el formato AccessEntity.{policy_name}. Puedes usar AccessEntity para acceder a los perfiles de las siguientes entidades:

  • Aplicación
  • Producto de API
  • Clave del cliente
  • Desarrollador

La política AccessEntity funciona como una búsqueda de base de datos de tiempo de ejecución basada en políticas. Puedes usar la información del perfil devuelta por esta política para habilitar comportamientos dinámicos, como el enrutamiento de endpoints condicional, la ejecución de flujos o la aplicación de políticas.

Usa la política AccessEntity para obtener datos de perfil de entidad en formato XML (o JSON en Apigee Hybrid) y colócalos en una variable. Identifica la entidad que quieres obtener especificando un tipo de entidad y uno o varios identificadores que indiquen qué entidad de ese tipo quieres. Más adelante, en otra política, puedes recuperar los datos del perfil de la entidad con otra política, como una política ExtractVariables o una política AssignMessage.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Acceder a entidades AppGroups desde AccessEntity

También puedes usar AccessEntity para obtener entidades AppGroup. Consulta los tipos de entidades e identificadores admitidos para ver las entidades relacionadas.

Para obtener información sobre AppGroups y las funciones compatibles, consulta Usar AppGroups para organizar la propiedad de las aplicaciones.

Ejemplos

En los siguientes ejemplos se muestra cómo se usa AccessEntity junto con las políticas ExtractVariables y AssignMessage para extraer el correo de un desarrollador y añadirlo al encabezado HTTP.

Obtener el correo del desarrollador para usarlo en otras políticas

Configure la política AccessEntity para especificar de qué perfil de entidad de Apigee se va a obtener la información, así como dónde se van a colocar los datos del perfil.

En el siguiente ejemplo, la política obtiene un perfil de entidad developer mediante una clave de API que se transfiere como parámetro de consulta para identificar al desarrollador. El perfil se coloca en una variable cuyo nombre sigue el formato AccessEntity.{policy_name}. Por lo tanto, la variable definida por esta política sería 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>

Usa otra política para recuperar el valor del perfil de entidad de la variable definida por AccessEntity.

En el ejemplo siguiente, una política ExtractVariables obtiene un valor de la variable AccessEntity.GetDeveloperProfile definida anteriormente por AccessEntity.

Tenga en cuenta que el valor recuperado se especifica como una expresión XPath en el elemento XMLPayload. El valor extraído se coloca en una 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 siguiente política AssignMessage obtiene el correo del desarrollador definido por la política 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>

Referencia de elemento

La estructura básica de una política AccessEntity es la siguiente:

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

Puedes acceder a varias entidades del mismo tipo agrupándolas en un elemento 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>

Atributos de <AccessEntity>

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

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Atributo Descripción Predeterminado Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

Elemento <EntityIdentifier>

Especifica la entidad concreta (del tipo indicado en EntityType) que se va a obtener.

<EntityIdentifier ref="value_variable" type="identifier_type"/>
Predeterminado N/A
Presencia Obligatorio
Tipo Cadena

Atributos

Atributo Descripción Predeterminado Presencia Tipo
ref

La variable que proporciona la fuente del identificador, como request.queryparam.apikey.

 N/A Obligatorio Cadena
tipo El tipo rellenado por la variable en el atributo ref, como consumerkey. Consulta la lista de tipos e identificadores de entidades admitidos. Obligatorio Cadena

Ejemplo

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

Elemento <EntityType>

Especifica el tipo de entidad que se va a obtener del almacén de datos.

<EntityType  value="entity_type"/>
Predeterminado N/A
Presencia Obligatorio
Tipo Cadena

Usa un elemento EntityIdentifier para especificar qué entidad del tipo indicado quieres. Para consultar una referencia de los tipos de entidades, consulta Tipos de entidades e identificadores admitidos.

Atributos

Atributo Descripción Predeterminado Presencia Tipo
valor Uno de los tipos de entidad admitidos. Consulta la lista de tipos de entidades e identificadores admitidos. Ninguno Obligatorio Cadena

Elemento <OutputFormat>

Especifica el formato que devuelve la política AccessEntity: XML o JSON.

<OutputFormat>XML</OutputFormat>
Predeterminado

XML

Si omite este elemento, el valor predeterminado será XML.
Presencia Opcional
Tipo Cadena (XML o JSON)

Elemento <SecondaryIdentifier>

Junto con EntityIdentifier, especifica un valor para identificar la instancia deseada del EntityType proporcionado.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
Predeterminado N/A
Presencia Opcional
Tipo Cadena

Usa SecondaryIdentifier cuando especificar solo un EntityIdentifier no garantice que obtengas una sola entidad. Consulte más información en el artículo Acotar los resultados con identificadores secundarios.

No se pueden usar varios elementos SecondaryIdentifier.

Atributos

Atributo Descripción Predeterminado Presencia Tipo
ref

La variable que proporciona la fuente del identificador, como request.queryparam.apikey.

 N/A Obligatorio Cadena
tipo El tipo rellenado por la variable en el atributo ref, como consumerkey. Consulta la lista de tipos e identificadores de entidades admitidos. Obligatorio Cadena

Ejemplo

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

Notas de uso

Acotar los resultados con identificadores secundarios

En el caso de algunas entidades, proporcionar un identificador puede no ser lo suficientemente específico para obtener la entidad que quieres. En esos casos, puede usar un identificador secundario para acotar los resultados.

Tu primera configuración de política, que puede ser amplia, podría tener este aspecto:

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

Como una aplicación puede estar asociada a varios productos de API, es posible que, si solo usas el ID de la aplicación, no obtengas el producto de API que quieres (podrías obtener solo el primero de varios productos coincidentes).

En su lugar, para obtener un resultado más exacto, puedes usar SecondaryIdentifier. Por ejemplo, puede que tengas las variables appname y developerid en el flujo, ya que se rellenan de forma predeterminada durante un intercambio de OAuth 2.0. Puedes usar los valores de esas variables en una política AccessEntity para obtener los detalles del perfil de la aplicación que hace la solicitud.

Tu configuración de política más específica podría tener este aspecto:

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

Tipos e identificadores de entidades admitidos

AccessEntity admite los siguientes tipos e identificadores de entidad.

Valor de EntityType Tipos de EntityIdentifier Tipos de 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

Ejemplo de XML de perfil de entidad

Para obtener el valor del perfil de entidad que quieras con XPath, debes conocer la estructura del XML del perfil. Para ver un ejemplo de la estructura, usa una llamada a la API de Apigee para obtener el XML de la entidad que quieras. Para obtener más información, consulta la referencia de la API de Apigee.

En las siguientes secciones se incluye el código de las llamadas a la API, junto con un ejemplo de XML de la llamada.

Aplicaciones

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

Consulta también Get app by app ID (Obtener aplicación por ID de aplicación) en la referencia de la API de Apigee.

O:

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

Consulta también Obtener detalles de la aplicación para desarrolladores en la referencia de la API de Apigee.

Perfil de ejemplo:

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

Producto de API

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

Consulta también Get API product (Obtener producto de API) en la referencia de la API de Apigee.

XPath de ejemplo que obtiene el segundo recurso de la API (URI) del producto de la API llamado weather_free:

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

Perfil de ejemplo devuelto como 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>

Clave del cliente

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

Consulta también Obtener detalles de la clave de una aplicación para desarrolladores en la referencia de la API de Apigee.

XPath de ejemplo:

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

Perfil de ejemplo:

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

Desarrollador

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

Consulta también Get developer en la referencia de la API de Apigee.

XPath de ejemplo:

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

Perfil de ejemplo:

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

Cuando se recupera el perfil de entidad especificado en la política AccessEntity, el objeto de perfil se añade al contexto del mensaje como una variable. Se puede acceder a ella como a cualquier otra variable, haciendo referencia al nombre de la variable. El nombre de la política AccessEntity proporcionado por el usuario se define como el prefijo de la variable.

Por ejemplo, si se ejecuta una política AccessEntity con el nombre GetDeveloper, el perfil se almacena en la variable AccessEntity.GetDeveloper. El perfil se puede analizar mediante un XPath definido en una política ExtractVariables que especifique AccessEntity.GetDeveloper como su origen.

Referencia de errores

Para obtener información relacionada, consulte Qué debe saber sobre los errores de las políticas y Gestión de errores.

Errores de tiempo de ejecución

Ninguno

Errores de implementación

Nombre del error Cadena de error Estado de HTTP Se produce cuando
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A El tipo de entidad utilizado debe ser uno de los tipos admitidos.

Temas relacionados