AccessEntity-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Symbol für Access Entity-Richtlinie

Was

Ruft Entitätsprofile ab, die Sie aus dem Apigee-Datenspeicher angeben. Die Richtlinie platziert das Profil in einer Variablen mit dem Namen AccessEntity.{policy_name}. Mit AccessEntity können Sie auf Profile für die folgenden Entitäten zugreifen:

  • App
  • API-Produkt
  • Consumer-Key
  • Entwickler

Die Richtlinie AccessEntity dient als richtlinienbasierter Laufzeitdatenbanksuche. Sie können die von dieser Richtlinie zurückgegebenen Profilinformationen verwenden, um das dynamische Verhalten zu aktivieren, z. B. bedingtes Endpunkt-Routing, Ablaufausführung und Richtlinienerzwingung.

Verwenden Sie die Richtlinie AccessEntity, um Entitätsprofildaten als XML (oder JSON in Apigee Hybrid) abzurufen und in eine Variable einzufügen. Geben Sie die Entität an, die Sie abrufen möchten. Dazu geben Sie einen Entitätstyp und eine oder mehrere Kennungen an, die die gewünschte Entität dieses Typs bestimmen. Später können Sie in einer anderen Richtlinie die Entitätsprofildaten mit einer anderen Richtlinie abrufen, z. B. mit einer ExtractVariables-Richtlinie oder AssignMessage-Richtlinie.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Auf AppGroups-Entitäten von AccessEntity zugreifen

Sie können auch AccessEntity verwenden, um AppGroup-Entitäten abzurufen. Verwandte Entitäten finden Sie unter Unterstützte Entitätstypen und -­kennzeichnungen.

Informationen zu AppGroups und unterstützten Funktionen finden Sie unter AppGroups zum Organisieren der App-Inhaberschaft verwenden.

Beispiele

Die folgenden Beispiele zeigen AccessEntity, die in Verbindung mit den Richtlinien ExtractVariables und AssignMessage verwendet werden, um die E-Mail eines Entwicklers zu extrahieren und dem HTTP-Header hinzuzufügen.

E-Mail-Adresse des Entwicklers zur Verwendung in anderen Richtlinien abrufen

Richten Sie die Richtlinie AccessEntity ein, um festzulegen, welches Entitätsprofil von Apigee abgerufen werden soll und wo die Profildaten platziert werden sollen.

Im folgenden Beispiel wird von der Richtlinie ein developer-Entitätsprofil abgerufen, wobei ein API-Schlüssel als Abfrageparameter übergeben wird, um den Entwickler zu identifizieren. Das Profil wird in einer Variablen platziert, deren Name dem Format AccessEntity.{policy_name} entspricht. Die von dieser Richtlinie festgelegte Variable wäre also 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>

Verwenden Sie eine andere Richtlinie, um den Wert des Entitätsprofils aus der von AccessEntity festgelegten Variablen abzurufen.

Im folgenden Beispiel wird ein ExtractVariables ruft die Richtlinie einen Wert aus der AccessEntity.GetDeveloperProfile zuvor festgelegte Variable AccessEntity, um die Option zu aktivieren.

Beachten Sie, dass der abgerufene Wert als XPath-Ausdruck im Element XMLPayload angegeben wird. Der extrahierte Wert wird in eine developer.email-Variable eingefügt.

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

Mit der folgenden Zuweisungsrichtlinie wird die Entwickler-E-Mail-Adresse abgerufen, die von der Richtlinie "ExtractVariables" festgelegt wurde.

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

Elementverweis

Die Grundstruktur einer AccessEntity-Richtlinie lautet:

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

Sie können auf mehrere Entitäten desselben Typs zugreifen, indem Sie sie in einem Identifiers - Element gruppieren:

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

<AccessEntity>-Attribute

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

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut Beschreibung Standard Präsenz
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen

 falsch Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Veraltet

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>
Standardeinstellung

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz Optional
Typ String

<EntityIdentifier>-Element

Gibt die spezifische Entität – des Typs in EntityType - an, der abgerufen werden soll.

<EntityIdentifier ref="value_variable" type="identifier_type"/>
Standard –
Präsenz Erforderlich
Typ String

Attribute

Attribut Beschreibung Standard Präsenz Typ
ref

Die Variable, die die Quelle der ID angibt, z. B. request.queryparam.apikey.

 – Erforderlich String
Typ Der Typ, der von der Variable im "ref"-Attribut ausgefüllt wird. wie consumerkey. Eine Liste der Werte finden Sie unter Unterstützte Entitätstypen und -kennzeichnungen. Erforderlich String

Beispiel

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

<EntityType>-Element

Gibt den Entitätstyp an, der aus dem Datenspeicher abgerufen werden soll.

<EntityType  value="entity_type"/>
Standard –
Präsenz Erforderlich
Typ String

Mit dem EntityIdentifier-Element kannst du die gewünschte Entität des angegebenen Typs angeben. Eine Referenz zu Entitätstypen finden Sie unter Unterstützte Entitätstypen und -kennzeichnungen.

Attribute

Attribut Beschreibung Standard Präsenz Typ
Wert Einer der unterstützten Entitätstypen. Eine Liste finden Sie unter unterstützte Entitätstypen und -kennzeichnungen. – Erforderlich String

<OutputFormat>-Element

Gibt das Format an, das von der AccessEntity-Richtlinie zurückgegeben wird: XML oder JSON.

<OutputFormat>XML</OutputFormat>
Standard

XML

Wenn Sie dieses Element weglassen, wird standardmäßig XML verwendet.
Präsenz Optional
Typ String (XML oder JSON)

<SecondaryIdentifier>-Element

Gibt in Verbindung mit EntityIdentifier einen Wert an, um die gewünschte Instanz des angegebenen EntityType zu identifizieren.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
Standard –
Präsenz Optional
Typ String

Verwenden Sie SecondaryIdentifier, wenn Sie nur eine EntityIdentifier angeben, ist nicht garantiert, dass Sie eine einzelne Entität erhalten. Weitere Informationen finden Sie unter Ergebnisse mit sekundären Kennzeichnungen einschränken.

Die Verwendung mehrerer SecondaryIdentifier-Elemente wird nicht unterstützt.

Attribute

Attribut Beschreibung Standard Präsenz Typ
ref

Die Variable, die die Quelle der ID angibt, z. B. request.queryparam.apikey.

 – Erforderlich String
Typ Der Typ, der von der Variable im "ref"-Attribut ausgefüllt wird. wie consumerkey. Eine Liste der Werte finden Sie unter Unterstützte Entitätstypen und -kennzeichnungen. Erforderlich String

Beispiel

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

Verwendungshinweise

Die Ergebnisse mit sekundären Kennungen eingrenzen

Bei einigen Entitäten ist die Zuweisung einer ID möglicherweise nicht spezifisch genug, um die gewünschte Entität zu erhalten. In diesen Fällen können Sie eine sekundäre Kennzeichnung verwenden, um die Ergebnisse einzugrenzen.

Ihre erste, möglicherweise allgemeine Richtlinienkonfiguration könnte so aussehen:

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

Da eine Anwendung mit mehreren API-Produkten verknüpft werden kann, kann die Verwendung der Anwendungs-ID möglicherweise nicht das gewünschte API-Produkt zurückgeben. Sie erhalten nur das erste von mehreren übereinstimmenden Produkten.

Stattdessen können Sie ein SecondaryIdentifier verwenden, um ein genaueres Ergebnis zu erhalten. Beispiel: Sie haben die Variablen appname und developerid im Ablauf, da sie standardmäßig während eines OAuth 2.0-Austauschs ausgefüllt werden. Sie können die Werte dieser Variablen in einer AccessEntity-Richtlinie verwenden, um Profildetails zur anfragenden Anwendung abzurufen.

Ihre spezifischere Richtlinienkonfiguration könnte so aussehen:

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

Unterstützte Entitätstypen und -kennzeichnungen

AccessEntity unterstützt die folgenden Entitätstypen und -kennzeichnungen.

EntityType-Wert EntityIdentifier-Typen SecondaryIdentifier-Typen
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

Beispiel für eine XML-Entitätsprofil-XML

Um den gewünschten Entitätsprofilwert mit XPath abzurufen, müssen Sie etwas über die Struktur der Profil-XML wissen. Verwenden Sie für ein Beispiel der Struktur einen Apigee API-Aufruf, um XML für die gewünschte Entität abzurufen. Weitere Informationen finden Sie in der Apigee API-Referenz.

Die folgenden Abschnitte enthalten Code für API-Aufrufe sowie Beispiel-XML aus dem Aufruf.

Apps

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

Siehe App nach App-ID abrufen in der Apigee API-Referenz.

oder:

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

Siehe auch Details zu Entwickleranwendungen abrufen in der Apigee API-Referenz.

Beispielprofil:

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

API-Produkt

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

Siehe auch API-Produkt abrufen in der Apigee API-Referenz.

Beispiel XPath, ruft die zweite API-Ressource (URI) aus dem API-Produkt weather_free ab:

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

Beispielprofil als XML zurückgegeben:

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

Consumer-Key

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

Siehe auch Schlüsseldetails für eine Entwickleranwendung abrufen in der Apigee API-Referenz.

Beispiel-XPath:

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

Beispielprofil:

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

Entwickler

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

Siehe auch Entwickler abrufen in der Referenz zur Apigee API.

Beispiel-XPath:

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

/Developer/Email/text()

Beispielprofil:

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

Ablaufvariablen

Wenn das in der Richtlinie AccessEntity angegebene Entitätsprofil abgerufen wird, wird das Profilobjekt als Variable zum Nachrichtenkontext hinzugefügt. Sie kann wie jede andere Variable mit Bezug auf den Variablennamen aufgerufen werden. Der vom Nutzer angegebene Name der Richtlinie AccessEntity wird als Variablenpräfix des Variablennamens festgelegt.

Wenn beispielsweise eine AccessEntity-Richtlinie mit dem Namen GetDeveloper ausgeführt wird, wird das Profil in der Variablen AccessEntity.GetDeveloper gespeichert. Das Profil kann dann mit einem in einer ExtractVariables-Richtlinie definierten XPath geparst werden. Dabei wird AccessEntity.GetDeveloper als Quelle angegeben.

Fehlerreferenz

Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

–

Bereitstellungsfehler

Fehlername Fehlerstring HTTP-Status Tritt auf, wenn Folgendes eintritt
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] – Der verwendete Entitätstyp muss einer der unterstützten Typen sein.

Weitere Informationen