Política AccessEntity

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

Consulta la documentación de Apigee Edge.

ícono de política de acceso de entidad

Qué

Recupera los perfiles de entidad que especificas 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:

  • App
  • Producto de API
  • Clave de consumidor
  • Desarrollador

La política AccessEntity funciona como una búsqueda de base de datos de entorno de ejecución basada en políticas. Puedes usar la información del perfil que muestra esta política para habilitar el comportamiento dinámico, como enrutamiento condicional de extremos, ejecución de flujo y aplicación de políticas.

Usa la política AccessEntity para obtener datos del perfil de entidad como XML (o JSON en Apigee Hybrid) y ponerlos en una variable. Identifica la entidad que deseas obtener especificando un tipo de entidad y uno o más identificadores que especifiquen qué entidad del 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 la política AssignMessage.

Esta política es una política extensible, y el uso de esta puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Accede a las entidades de AppGroups desde AccessEntity

También puedes usar AccessEntity para recuperar entidades de AppGroups. Consulta Identificadores y tipos de entidades admitidos para ver entidades relacionadas.

Si deseas obtener información sobre AppGroups y la funcionalidad compatible, consulta Usa AppGroups para organizar la propiedad de las apps.

Muestras

En los siguientes ejemplos, se muestra AccessEntity, que se usa junto con las políticas ExtractVariables y AssignMessage para extraer el correo electrónico de un desarrollador y agregarlo al encabezado HTTP.

Cómo obtener el correo electrónico de un desarrollador para usar en otras políticas

Configura la política AccessEntity para especificar qué perfil de entidad se debe obtener de Apigee y dónde ubicar los datos del perfil.

En el siguiente ejemplo, la política obtiene un perfil de entidad developer mediante una clave de API que se pasa como un 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 establecida 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 la entidad de la variable que establece AccessEntity.

En el siguiente ejemplo, una política ExtractVariables recupera un valor de la variable AccessEntity.GetDeveloperProfile que estableció antes AccessEntity.

Ten 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 AllocationMessage recupera el correo electrónico del desarrollador que establece 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 elementos

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 si las agrupas 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 <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 principales de las políticas:

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.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

 N/A Obligatorio
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente:

 falso Opcional
enabled

Configúralo como true para aplicar la política.

Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.

 true Opcional
async

Este atributo dejó de estar disponible.

 falso Obsoleta

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Predeterminada

N/A

Si omites este elemento, se usa el valor del atributo name de la política.
Presencia Opcional
Tipo String

Elemento <EntityIdentifier>

Especifica la entidad en particular (del tipo especificado en EntityType) que se desea 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 String
tipo Indica el tipo que completó la variable en el atributo "ref". como consumerkey. Consulta Identificadores y tipos de entidades admitidos para obtener una lista de valores. Obligatorio String

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 recuperará del almacén de datos.

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

Usa un elemento EntityIdentifier para especificar qué entidad del tipo específico deseas. Para obtener una referencia de los tipos de entidades, consulta Identificadores y tipos de entidades admitidos.

Atributos

Atributo Descripción Predeterminado Presencia Tipo
valor Uno de los tipos de entidad compatibles. Consulta Identificadores y tipos de entidades admitidos para ver una lista. Ninguno Obligatorio String

Elemento <OutputFormat>

Especifica el formato que muestra la política de acceso de XML: XML o JSON.

<OutputFormat>XML</OutputFormat>
Predeterminado

XML

Si omites este elemento, el valor predeterminado es XML.
Presence Opcional
Tipo String (XML o JSON)

Elemento <SecondaryIdentifier>

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

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

Usa SecondaryIdentifier cuando especifiques solo un EntityIdentifier no garantiza que obtengas una sola entidad. Para obtener más información, consulta Restringir los resultados con identificadores secundarios.

No se admite el uso de 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 String
tipo Indica el tipo que completó la variable en el atributo "ref". como consumerkey. Consulta Identificadores y tipos de entidades admitidos para obtener una lista de valores. Obligatorio String

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:

Restringe los resultados con identificadores secundarios

Para algunas entidades, proporcionar un identificador puede no ser lo suficientemente específico a fin de obtener la entidad que deseas. En esos casos, puedes usar un identificador secundario para limitar los resultados.

La primera configuración de política posiblemente general podría verse de la siguiente manera:

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

Dado que una app puede estar asociada a varios productos de API, usar solo el ID de la app podría no mostrar el producto de API que deseas (quizás obtengas solo el primer producto de varios que coinciden).

En cambio, para obtener un resultado más exacto, puedes usar un SecondaryIdentifier. Por ejemplo, es posible que tengas variables appname y developerid en el flujo, ya que estas se propagan de forma predeterminada durante un intercambio de OAuth 2.0. Puedes usar los valores de esas variables en una política AccessEntity para obtener detalles del perfil sobre la app solicitante.

La configuración más específica de la política podría verse de la siguiente manera:

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

Identificadores y tipos de entidades admitidos

AccessEntity admite los siguientes identificadores y tipos de entidades.

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 del XML del perfil de entidad

Para recuperar el valor de perfil de la entidad que deseas con XPath, deberás saber algo sobre la estructura del XML del perfil. Si deseas ver un ejemplo de la estructura, usa una llamada a la API de Apigee a fin de obtener XML para la entidad que deseas. Para obtener más detalles, consulta la referencia de la API de Apigee.

Las siguientes secciones incluyen código para las llamadas a la API y el XML de ejemplo de la llamada.

Apps

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

Consulta también Obtén la app por ID de app en la referencia de la API de Apigee.

O el siguiente:

$ 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 Obtén detalles de apps para desarrolladores en la referencia de la API de Apigee.

Perfil de muestra

<?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 Obtén un producto de API en la referencia de la API de Apigee.

XPath de muestra, recupera el segundo recurso de API (URI) del producto de API llamado weather_free:

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

El perfil de ejemplo se muestra 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 de consumidor

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 Obtén detalles clave de una app para desarrolladores en la referencia de la API de Apigee.

XPath de ejemplo:

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

Perfil de muestra

<?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 Obtén un desarrollador 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 muestra

<?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 agrega al contexto del mensaje como una variable. Se puede acceder como cualquier otra variable, con referencia al nombre de variable. El nombre que proporciona el usuario de la política AccessEntity se establece como el prefijo de la variable del nombre de la variable.

Por ejemplo, si se ejecuta una política AccessEntity con el nombre GetDeveloper, el perfil se almacena en la variable llamada AccessEntity.GetDeveloper. El perfil se puede analizar con una XPath definida en una política de extracción que especifica AccessEntity.GetDeveloper como su fuente.

Referencia de errores

Para obtener información relacionada, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Ninguno

Errores en la implementación

Nombre del error String de error Estado de HTTP Ocurre cuando
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A El tipo de entidad que se use debe ser uno de los tipos compatibles.

Temas relacionados