Criterio AccessEntity

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

icona criterio entità di accesso

Cosa

Recupera i profili di entità specificati dal datastore Apigee. La norma inserisce profilo in una variabile il cui nome segue il formato AccessEntity.{policy_name}. Tu può utilizzare AccessEntity per accedere ai profili per le seguenti entità:

  • App
  • Prodotto API
  • Chiave utente
  • Sviluppatore

Il criterio AccessEntity funziona come una ricerca di database di runtime basata su criteri. Tu puoi utilizzare le informazioni del profilo restituite da questo criterio per attivare comportamenti dinamici, ad esempio routing condizionale degli endpoint, esecuzione del flusso, applicazione dei criteri.

Utilizza il criterio AccessEntity per ottenere i dati del profilo entità come XML (o JSON in Apigee hybrid) e inserirlo in una variabile. Identifica l'entità da ottenere specificando un'entità e uno o più identificatori che specificano quale entità di quel tipo vuoi. Più avanti, tra in un altro criterio, puoi recuperare i dati del profilo dell'entità con un altro criterio, ad esempio Criterio ETL o criterioAssignMessage.

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.

Accedi alle entità AppGroups da AccessEntity

Puoi anche utilizzare AccessEntity per recuperare le entità AppGroup. Consulta Tipi di entità e identificatori supportati per le entità correlate.

Per informazioni su AppGroups e sulle funzionalità supportate, vedi Utilizzare AppGroups per organizzare la proprietà delle app.

Esempi

Gli esempi riportati di seguito mostrano l'uso della classe AccessEntity in combinazione con Criteri ExtractVariables e AssignMessage per estrarre il valore dell'email e aggiungerla all'intestazione HTTP.

Richiedere l'indirizzo email dello sviluppatore da utilizzare in altri criteri

Configura il criterio AccessEntity per specificare da quale profilo entità eseguire l'accesso Apigee e dove inserire i dati del profilo.

Nell'esempio seguente, il criterio ottiene un profilo di entità developer utilizzando un Chiave API passata come parametro di query per identificare lo sviluppatore. Il profilo si trova in una il cui nome segue il formato AccessEntity.{policy_name}. Quindi la variabile impostato da questo criterio sarà 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>

Utilizza un altro criterio per recuperare il valore del profilo dell'entità dalla variabile impostata da AccessEntity.

Nell'esempio seguente, un criterio ExtractVariables recupera un valore da la variabile AccessEntity.GetDeveloperProfile impostata in precedenza AccessEntity.

Tieni presente che il valore recuperato viene specificato come espressione XPath nella Elemento XMLPayload. Il valore estratto viene inserito in un Variabile 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>

Il seguente criterioAssignMessage recupera l'email dello sviluppatore impostata dal parametro Criterio ETL (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>

Riferimento elemento

La struttura di base di un criterio AccessEntity è:

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

Puoi accedere a più entità dello stesso tipo raggruppandole in una Identifiers elemento:

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

&lt;AccessEntity&gt; attributi

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/A Obbligatorio
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche:

 false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

 true Facoltativo
async

Questo attributo è obsoleto.

 false Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

&lt;EntityIdentifier&gt; elemento

Specifica l'entità particolare, del tipo specificato in EntityType, da ottenere.

<EntityIdentifier ref="value_variable" type="identifier_type"/>
Predefinito N/D
Presenza Obbligatorio
Tipo Stringa

Attributi

Attributo Descrizione Predefinito Presenza Tipo
riferimento

La variabile che fornisce l'origine dell'identificatore, ad esempio request.queryparam.apikey.

 N/D Obbligatorio Stringa
tipo Il tipo compilato dalla variabile nell'attributo ref. come consumerkey. Consulta Tipi di entità e identificatori supportati per un elenco di valori. Obbligatorio Stringa

Esempio

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

&lt;EntityType&gt; elemento

Specifica il tipo di entità da recuperare dal datastore.

<EntityType  value="entity_type"/>
Predefinito N/D
Presenza Obbligatorio
Tipo Stringa

Utilizza un elemento EntityIdentifier per specificare quale entità del tipo specificato vuoi. Per un riferimento sui tipi di entità, consulta Tipi di entità e identificatori supportati.

Attributi

Attributo Descrizione Predefinito Presenza Tipo
valore Uno dei tipi di entità supportati. Consulta Tipi di entità supportati e identificatori per un elenco. Nessuno Obbligatorio Stringa

&lt;OutputFormat&gt; elemento

Specifica il formato restituito dal criterio AccessEntity: XML o JSON.

<OutputFormat>XML</OutputFormat>
Predefinito

XML

Se ometti questo elemento, il valore predefinito è XML.
Presenza Facoltativo
Tipo Stringa (XML o JSON)

&lt;SecondaryIdentifier&gt; elemento

Oltre a EntityIdentifier, specifica un valore per identificare il dell'oggetto EntityType specificato.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
Predefinito N/D
Presenza Facoltativo
Tipo Stringa

Usa SecondaryIdentifier quando specifichi solo un EntityIdentifier non garantiranno la presenza di una singola entità. Consulta la sezione Restringimento con identificatori secondari per saperne di più.

L'utilizzo di più elementi SecondaryIdentifier non è supportato.

Attributi

Attributo Descrizione Predefinito Presenza Tipo
riferimento

La variabile che fornisce l'origine dell'identificatore, ad esempio request.queryparam.apikey.

 N/D Obbligatorio Stringa
tipo Il tipo compilato dalla variabile nell'attributo ref. come consumerkey. Consulta Tipi di entità e identificatori supportati per un elenco di valori. Obbligatorio Stringa

Esempio

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

Note sull'utilizzo

Limitazione dei risultati con identificatori secondari

Per alcune entità, fornire un identificatore potrebbe non essere abbastanza specifico per ottenere l'entità che desiderato. In questi casi, puoi utilizzare un identificatore secondario per restringere i risultati.

La tua prima configurazione dei criteri, potenzialmente ampia, potrebbe avere il seguente aspetto:

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

Poiché un'app può essere associata a più prodotti API, l'utilizzo del solo ID app potrebbe non restituire il prodotto API che vuoi (potresti ricevere solo il primo di più prodotti corrispondenti).

Invece, per ottenere un risultato più preciso, puoi utilizzare un SecondaryIdentifier. Per Ad esempio, nel flusso potrebbero essere presenti variabili appname e developerid perché vengono compilate per impostazione predefinita durante uno scambio OAuth 2.0. Puoi utilizzare i valori queste variabili in un criterio AccessEntity per ottenere i dettagli del profilo della richiesta dell'app.

La configurazione dei criteri più specifica potrebbe avere il seguente aspetto:

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

Tipi di entità e identificatori supportati

AccessEntity supporta i seguenti tipi di entità e identificatori.

Valore EntityType Tipi di EntityIdentifier Tipi di SecondIdentifier
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

XML di profilo entità di esempio

Per recuperare il valore del profilo entità che vuoi con XPath, devi sapere qualcosa la struttura del file XML del profilo. Per un esempio della struttura, usa una chiamata API Apigee per XML per l'entità che ti interessa. Per maggiori dettagli, fai riferimento all'API Apigee riferimento.

Le seguenti sezioni includono il codice per le chiamate API, oltre all'XML di esempio della chiamata.

App

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

Vedi anche Scarica l'app per ID app nel riferimento API Apigee.

Oppure:

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

Vedi anche Ottieni i dettagli dell'app sviluppatore nel riferimento API Apigee.

Profilo di esempio:

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

Prodotto API

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

Vedi anche Ottieni API nel riferimento API Apigee.

XPath di esempio recupera la seconda risorsa API (URI) dal prodotto API denominato weather_free:

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

Profilo di esempio restituito come 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>

Chiave utente

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

Vedi anche Ottieni i dettagli chiave per un'app sviluppatore nel riferimento API Apigee.

XPath di esempio:

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

Profilo di esempio:

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

Sviluppatore

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

Vedi anche Trovare uno sviluppatore nella di riferimento API Apigee.

XPath di esempio:

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

/Developer/Email/text()

Profilo di esempio:

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

Variabili di flusso

Quando viene recuperato il profilo entità specificato nel criterio AccessEntity, viene restituito il valore profilo viene aggiunto al contesto del messaggio come variabile. È accessibile come qualsiasi altro facendo riferimento al nome della variabile. Il nome fornito dall'utente per il criterio AccessEntity è impostato come prefisso del nome della variabile.

Ad esempio, se viene eseguito un criterio AccessEntity con nome GetDeveloper, il profilo viene memorizzato nella variabile denominata AccessEntity.GetDeveloper. Il profilo può quindi essere analizzato utilizzando XPath definito in un criterio ExtractVariables che specifica AccessEntity.GetDeveloper come origine.

Messaggi di errore

Per informazioni correlate, consulta gli articoli Cosa devi sapere sugli errori relativi ai criteri e Gestione degli errori.

Errori di runtime

Nessuno.

Errori di deployment

Nome errore Stringa di errore Stato HTTP Si verifica quando
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A Il tipo di entità utilizzato deve essere uno dei tipi supportati.

Argomenti correlati