Política AccessEntity

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

Recupera los perfiles de entidad que especificas del almacén de datos de Apigee Edge. 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
  • Empresa
  • Desarrollador de la empresa
  • 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 los datos del perfil de entidad como XML y ponerlos en una variable. Para identificar la entidad que deseas obtener, especifica 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.

Ejemplos

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 obtener de Edge, así como dónde 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 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 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>

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 Predeterminada 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.

No disponible Obligatorias
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.

false 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.

false Funciones obsoletas

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

No disponible

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

Presencia Opcional
Tipo Cadena

Elemento <EntityIdentifier>

Especifica la entidad en particular (del tipo especificado en EntityType) que se desea obtener.

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

Predeterminada

No disponible

Presencia

Obligatorias

Tipo

Cadena

Atributos

Atributo Descripción Predeterminada Presencia Tipo
ref

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

No disponible Obligatorio. Cadena
tipo Indica el tipo que completó la variable en el atributo "ref". como consumerkey. Consulta los identificadores y tipos de entidades para obtener una lista de valores. Obligatorio. Cadena

Ejemplo

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

Elemento <EntityType>

Especifica el tipo de entidad que se recuperará del almacén de datos.

<EntityType  value="entity_type"/>

Predeterminada

No disponible

Presencia

Obligatorias

Tipo

Cadena

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.

Atributos

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

Elemento <SecondaryIdentifier>

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

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

Predeterminada

No disponible

Presencia

Opcional

Tipo

Cadena

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 Predeterminada Presencia Tipo
ref

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

No disponible Obligatorio. Cadena
tipo Indica el tipo que completó la variable en el atributo "ref". como consumerkey. Consulta los identificadores y tipos de entidades para obtener una lista de valores. 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:

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

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. Para ver un ejemplo de la estructura, usa una llamada a la API de administración a fin de obtener el XML de la entidad que desees. Para obtener más detalles, consulta la referencia de la API de administración.

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

Aplicaciones

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

Consulta también Cómo obtener una app en una organización por ID de app en la referencia de la API de Edge Management.

o:

$ 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

Consulta también Obtén detalles de la app de desarrollador en la referencia de la API de Edge Management.

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  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

Consulta también Cómo obtener un producto de API en la referencia de la API de Edge Management.

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>

Empresa

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

Consulta también Obtén detalles de la empresa en la referencia de la API de Edge Management.

Perfil de muestra

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

Desarrollador de la empresa

$ 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

Perfil de muestra

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

Clave de consumidor

$ 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

Consulta también Cómo obtener detalles de la clave para una app de desarrollador en la referencia de la API de Edge Management.

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 -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

Consulta también Obtener desarrollador en la referencia de la API de Edge Management.

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

Por ejemplo, si se ejecuta una política AccessEntity con el nombre GetDeveloper, el perfil con formato XML se almacena en la variable llamada AccessEntity.GetDeveloper. El perfil con formato XML se puede analizar mediante una XPath definida en una política ExtractVariables que especifica AccessEntity.GetDeveloper como la fuente.

Referencia de errores

Para obtener información relacionada, consulta Lo que debes saber sobre los errores de políticas y Cómo manejar fallas.

Errores de entorno de ejecución

Ninguno

Errores en la implementación

Nombre del error Cadena de errores Estado de HTTP Ocurre cuando
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] No disponible El tipo de entidad que se use debe ser uno de los tipos admitidos.

Temas relacionados