<ph type="x-smartling-placeholder"></ph>
Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur
Apigee X-Dokumentation. Weitere Informationen
Was
Mit der Richtlinie zum Prüfen des API-Schlüssels können Sie die Verifizierung von API-Schlüsseln zur Laufzeit erzwingen, sodass nur Anwendungen mit genehmigten API-Schlüsseln auf Ihre APIs zugreifen können. Mit dieser Richtlinie wird sichergestellt, dass API-Schlüssel gültig sind, nicht widerrufen wurden und für die Nutzung der spezifischen Ressourcen freigegeben wurden, die mit Ihren API-Produkten verknüpft sind.
Beispiele
Schlüssel im Abfrageparameter
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
In diesem Beispiel erwartet die Richtlinie den API-Schlüssel in einer Ablaufvariablen namens request.queryparam.apikey
. Die Variable request.queryparam.{name}
ist eine Standard-Edge-Flussvariable, die mit dem Wert eines übergebenen Abfrageparameters ausgefüllt wird.
in der Clientanfrage.
Der folgende curl
-Befehl übergibt den API-Schlüssel in einem Abfrageparameter:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Schlüssel im Header
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
In diesem Beispiel erwartet die Richtlinie den API-Schlüssel in einer Ablaufvariablen namens request.header.x-apikey
. Die Variable request.header.{name}
ist eine Standard-Edge-Flussvariable, die mit dem Wert eines übergebenen Headers gefüllt wird.
in der Clientanfrage.
Im folgenden cURL wird gezeigt, wie der API-Schlüssel in einem Header übergeben wird:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Schlüssel in der Variablen
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
Die Richtlinie kann auf jede Variable verweisen, die den Schlüssel enthält. Die Richtlinie in diesem Beispiel extrahiert den API-Schlüssel aus einer Variablen mit dem Namen requestAPIKey.key.
Wie diese Variable ausgefüllt wird, liegt ganz bei Ihnen. Sie können beispielsweise die Richtlinie "Variablen extrahieren" verwenden, um requestAPIKey.key aus einem Abfrageparameter namens myKey auszufüllen, wie unten gezeigt:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Ablaufvariablen für Zugriffsrichtlinien
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Edge füllt beim Ausführen des API-Schlüssels „Verify API Key“ automatisch einen Satz von Flussvariablen aus für einen gültigen API-Schlüssel. Sie können diese Variablen verwenden, um auf Informationen wie den Namen der App, die App-ID und Informationen zum Entwickler oder Unternehmen zuzugreifen, der die App registriert hat. Im obigen Beispiel verwenden Sie die Richtlinie "Nachricht zuweisen", um auf den Vornamen, den Nachnamen und die E-Mail-Adresse des Entwicklers zuzugreifen, nachdem der API-Schlüssel verifiziert wurde.
Diese Variablen haben das Präfix:
verifyapikey.{policy_name}
In diesem Beispiel lautet der Name der API-Schlüsselrichtlinie "Verify-api-key". Daher verweisen Sie auf den Vornamen des Entwicklers, der die Anfrage stellt, indem Sie auf die Variable verifyapikey.verify-api-key.developer.firstName.
zugreifen.
Lerne Edge
Informationen zur Richtlinie "API-Schlüssel prüfen"
Wenn ein Entwickler eine App in Edge registriert, generiert Edge automatisch einen Consumer-Schlüssel und geheimen Paar aus. Sie können das Consumer-Key-Secret-Paar der App in der Edge-Benutzeroberfläche sehen oder darauf zugreifen über die Edge-API.
Zum Zeitpunkt der App-Registrierung wählt der Entwickler ein oder mehrere API-Produkte aus, die mit der App verknüpft werden sollen. Ein API-Produkt ist eine Sammlung von Ressourcen, auf die über API-Proxys zugegriffen werden kann. Der Entwickler übergibt dann den API-Schlüssel (Consumer-Key) als Teil jeder Anfrage an eine API in einem der Anwendung zugeordneten API-Produkt. Weitere Informationen finden Sie unter Veröffentlichungsübersicht.
API-Schlüssel können als Authentifizierungstoken verwendet werden. Sie können aber auch zum Abrufen von OAuth-Zugriffstokens verwendet werden. In OAuth werden API-Schlüssel als "Client-ID" bezeichnet. Die Namen können austauschbar verwendet werden. Weitere Informationen finden Sie unter OAuth-Startseite.
Edge füllt beim Ausführen der Richtlinie zum Überprüfen des API-Schlüssels automatisch eine Reihe von Flussvariablen aus. Weitere Informationen zu Flow-Variablen finden Sie weiter unten.
Elementreferenz
Die folgenden Elemente und Attribute können Sie für diese Richtlinie konfigurieren:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
<VerifyAPIKey>-Attribute
Das folgende Beispiel zeigt die Attribute für das Tag <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
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 Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie Legen Sie |
false | Optional |
enabled |
Setzen Sie den Wert auf Legen Sie |
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 |
---|---|
Präsenz | Optional |
Typ | String |
<APIKey>-Element
Mit diesem Element wird die Flussvariable angegeben, die den API-Schlüssel enthält. In der Regel sendet der Client den API-Schlüssel in einem Abfrageparameter, einem HTTP-Header oder einem Formularparameter. Wenn der Schlüssel beispielsweise in einem Header namens x-apikey
gesendet wird, ist der Schlüssel in der Variable request.header.x-apikey
zu finden.
Standard | – |
---|---|
Präsenz | Erforderlich |
Typ | String |
Attribute
In der folgenden Tabelle werden die Attribute des Elements <APIKey>
beschrieben.
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
ref |
Ein Verweis auf die Variable, die den API-Schlüssel enthält. Pro Richtlinie ist nur ein Standort zulässig. |
– | Erforderlich |
Beispiele
In diesen Beispielen werden der Schlüssel und Parameter wie ein Header mit dem Namen x-apikey
übergeben.
Als Abfrageparameter:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
Als HTTP-Header:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
Als HTTP-Formularparameter:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Schemas
Ablaufvariablen
Wenn eine Richtlinie zum Überprüfen des API-Schlüssels für einen gültigen API-Schlüssel erzwungen wird, füllt Edge einen Satz von Fluss aus Variablen. Diese Variablen sind für Richtlinien oder Code verfügbar, die später im Ablauf ausgeführt werden. Sie werden häufig verwendet, um auf Grundlage des Attributs des API-Schlüssels wie dem Anwendungsnamen oder dem API-Produkt, das zur Autorisierung des Schlüssels verwendet wird, um eine benutzerdefinierte Verarbeitung oder benutzerdefinierte Attribute des API-Schlüssels durchzuführen.
Die Richtlinie füllt verschiedene Arten von Ablaufvariablen aus, einschließlich:
- Allgemein
- App
- Entwickler
- Company
- Analyse
Jeder Typ von Ablaufvariablen hat ein anderes Präfix. Alle Variablen sind Skalare, mit Ausnahme derer, die als Arrays angegeben sind.
Allgemeine Ablaufvariablen
In der folgenden Tabelle sind die allgemeinen Ablaufvariablen aufgeführt, die von der Richtlinie "API-Schlüssel prüfen" ausgefüllt werden. Diese Variablen haben das Präfix:
verifyapikey.{policy_name}
Beispiel: verifyapikey.{policy_name}.client_id
Folgende Variablen sind verfügbar:
Variable | Beschreibung |
---|---|
client_id |
Der Consumer-Key (auch als API-Schlüssel oder App-Schlüssel bezeichnet), der von der anfordernden App bereitgestellt wird. |
client_secret |
Das Consumer-Secret für den Consumer-Key. |
redirection_uris |
Alle Weiterleitungs-URIs in der Anfrage |
developer.app.id |
ID der Entwickler-App, von der die Anfrage stammt. |
developer.app.name |
Der App-Name der Entwickler-App, von der die Anfrage stammt. |
developer.id |
Die ID des Entwicklers, der als Inhaber der anfragenden App registriert ist |
developer.{custom_attrib_name} |
Alle benutzerdefinierten Attribute, die aus dem App-Schlüsselprofil abgeleitet wurden. |
DisplayName |
Der Wert des Attributs <DisplayName> der Richtlinie. |
failed |
Wird auf "true" gesetzt, wenn die API-Schlüsselvalidierung fehlschlägt. |
{custom_app_attrib} |
Jedes benutzerdefinierte Attribut, das aus dem App-Profil abgeleitet wird. Geben Sie den Namen des benutzerdefinierten Attributs an. |
apiproduct.name* |
Der Name des API-Produkts, das zur Validierung der Anfrage verwendet wird. |
apiproduct.{custom_attrib_name}* |
Jedes benutzerdefinierte Attribut, das vom API-Produktprofil abgeleitet wird. |
apiproduct.developer.quota.limit* |
Das für das API-Produkt festgelegte Kontingentlimit, falls vorhanden. |
apiproduct.developer.quota.interval* |
Das für das API-Produkt festgelegte Kontingentintervall, falls vorhanden. |
apiproduct.developer.quota.timeunit* |
Die Kontingenteinheit, die für das API-Produkt festgelegt wurde, sofern vorhanden. |
* API-Produktvariablen werden automatisch ausgefüllt, wenn die API-Produkte
mit gültiger Umgebung, Proxys und Ressourcen (abgeleitet von
proxy.pathsuffix ). Eine Anleitung zum Einrichten von API-Produkten finden Sie unter
Verwenden der Kante
Management API in die Veröffentlichung von APIs ändern. |
App-Ablaufvariablen
Folgende Ablaufvariablen, die Informationen über die Anwendung enthalten, werden durch die Richtlinie ausgefüllt. Diese Variablen haben das Präfix:
verifyapikey.{policy_name}.app
.
Beispiel:
verifyapikey.{policy_name}.app.name
Folgende Variablen sind verfügbar:
Variable | Beschreibung |
---|---|
name |
Der Name der Anwendung |
id |
ID der App |
accessType |
Wird von Apigee nicht verwendet. |
callbackUrl |
Die Callback-URL der App wird normalerweise nur für OAuth verwendet. |
DisplayName |
Der Anzeigename der App |
status |
Der Status der Anwendung, z. B. "Genehmigt" oder "Widerruf". |
apiproducts |
Ein Array, das die Liste der API-Produkte enthält, die der App zugeordnet sind. |
appFamily |
Jede App-Familie, in der die App enthalten ist, oder "Standard". |
appParentStatus |
Der Status der übergeordneten Anwendung, z. B. "Aktiv" oder "Inaktiv" |
appType |
Der App-Typ, entweder "Unternehmen" oder "Entwickler". |
appParentId |
Die ID der übergeordneten App. |
created_at |
Datum und Uhrzeit, zu der die App erstellt wurde. |
created_by |
Die E-Mail-Adresse des Entwicklers, der die App erstellt hat. |
last_modified_at |
Das Datum und der Zeitstempel der letzten App-Aktualisierung. |
last_modified_by |
Die E-Mail-Adresse des Entwicklers, der die App zuletzt aktualisiert hat. |
{app_custom_attributes} |
Jedes benutzerdefinierte App-Attribut. Geben Sie den Namen des benutzerdefinierten Attributs an. |
Entwickler-Ablaufvariablen
Die folgenden Ablaufvariablen mit Informationen über den Entwickler werden von der Richtlinie ausgefüllt. Diese Variablen haben das Präfix:
verifyapikey.{policy_name}.developer
Beispiel:
verifyapikey.{policy_name}.developer.id
Folgende Variablen sind verfügbar:
Variable | Beschreibung |
---|---|
id |
Gibt {org_name}@@@{developer_id} zurück |
userName |
Nutzername des Entwicklers |
firstName |
Vorname des Entwicklers |
lastName |
Nachname des Entwicklers |
email |
E-Mail-Adresse des Entwicklers |
status |
Status des Entwicklers als aktiv, inaktiv oder login_lock |
apps |
Eine Reihe von Apps, die dem Entwickler zugeordnet sind. |
created_at |
Das Datum/die Uhrzeit, zu der der Entwickler erstellt wurde. |
created_by |
Die E-Mail-Adresse des Nutzers, der den Entwickler erstellt hat. |
last_modified_at |
Der Datums-/Zeitstempel, zu dem der Entwickler zuletzt geändert wurde. |
last_modified_by |
Die E-Mail-Adresse des Nutzers, der den Entwickler geändert hat. |
{developer_custom_attributes} |
Alle benutzerdefinierten Entwicklerattribute. Geben Sie den Namen des benutzerdefinierten Attributs an. |
Company |
Der Name des Unternehmens, sofern vorhanden, das mit dem Entwickler verknüpft ist. |
Unternehmens-Ablaufvariablen
Die folgenden Ablaufvariablen mit Informationen über das Unternehmen werden von der Richtlinie ausgefüllt. Diese Variablen haben das Präfix:
verifyapikey.{policy_name}.company
Beispiel:
verifyapikey.{policy_name}.company.name
Folgende Variablen sind verfügbar:
Variable | Beschreibung |
---|---|
name |
Name des Unternehmens |
displayName |
Anzeigename des Unternehmens |
id |
ID des Unternehmens |
apps |
Ein Array, das die Liste der Unternehmens-Apps enthält. |
appOwnerStatus |
Der Status des App-Inhabers als aktiv, inaktiv oder login_lock.
|
created_at |
Datum und Uhrzeit, zu der das Unternehmen erstellt wurde. |
created_by |
Die E-Mail-Adresse des Nutzers, der das Unternehmen erstellt hat. |
last_modified_at |
Der Datums-/Zeitstempel, zu dem das Unternehmen zuletzt geändert wurde. |
last_modified_by |
Die E-Mail-Adresse des Nutzers, der das Unternehmen zuletzt geändert hat. |
{company_custom_attributes} |
Alle benutzerdefinierten Unternehmens-Attribute. Geben Sie den Namen des benutzerdefinierten Attributs an. |
Analytics-Variablen
Die folgenden Variablen werden in Analytics automatisch ausgefüllt, wenn eine gültige API-Schlüsselrichtlinie für einen gültigen API-Schlüssel erzwungen wird. Diese Variablen werden nur durch die Richtlinie "API-Schlüssel überprüfen" und die OAuth-Richtlinien ausgefüllt.
Die Variablen und Werte können als Dimensionen zum Erstellen von Analytics-Berichten verwendet werden, um Einblicke in die Verbrauchsmuster von Entwicklern und Apps zu erhalten.
- apiproduct.name
- developer.app.name
- Client-ID
- developer.id
Fehlerreferenz
Dieser Abschnitt beschreibt die Fehlercodes und Fehlermeldungen, die zurückgegeben werden, und die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.
Laufzeitfehler
Diese Fehler können bei Ausführung der Richtlinie auftreten.
Fehlercode | HTTP-Status | Ursache |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | Das Unternehmen, das mit der Entwickler-App verknüpft ist, für die der von dir verwendete API-Schlüssel verwendet wird, hat einen inaktiv sein. Ist der Status eines Unternehmens auf inaktiv gesetzt, können Sie nicht auf die Entwickler oder Apps, die mit diesem Unternehmen verknüpft sind. Ein Administrator der Organisation kann den Status eines Unternehmens ändern mithilfe der Verwaltungs-API. Siehe Status festlegen eines Unternehmens. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Der Entwickler, der die den verwendeten API-Schlüssel besitzende Entwickler-App erstellt hat, hat den Status "Inaktiv". Wird der Status eines App-Entwicklers auf "Inaktiv" gesetzt, werden alle von diesem Entwickler erstellten Entwickler-Apps deaktiviert. Ein Administrator mit entsprechenden Berechtigungen (z. B. ein Organisationsadministrator) kann den Status eines Entwicklers auf folgende Weise ändern:
|
keymanagement.service.invalid_client-app_not_approved |
401 | Die mit dem API-Schlüssel verknüpfte Entwickler-App wird widerrufen. Eine widerrufene App kann auf API-Produkte zugreifen und keine von Apigee Edge verwalteten APIs aufrufen können. Ein Administrator der Organisation kann den Status einer Entwickler-App mithilfe der Verwaltungs-API ändern Weitere Informationen finden Sie unter . Entwickler-App genehmigen oder widerrufen |
oauth.v2.FailedToResolveAPIKey |
401 | Die Richtlinie erwartet, den API-Schlüssel in einer im <APIKey>-Element der Richtlinie angegebenen Variablen zu finden. Dieser Fehler tritt auf, wenn die erwartete Variable nicht existiert (die Aufgabe kann nicht aufgelöst werden). |
oauth.v2.InvalidApiKey |
401 | Edge hat einen API-Schlüssel erhalten, er ist aber ungültig. Wenn Edge den Schlüssel in seiner -Datenbank muss genau mit der übereinstimmen, die in der Anfrage gesendet wurde. Wenn die API funktioniert hat, sorgen Sie dafür, dass der Schlüssel nicht neu generiert wurde. Wenn der Schlüssel neu generiert wurde, wird diese Fehlermeldung angezeigt, wenn Sie versuchen, den alten Schlüssel zu verwenden. Weitere Informationen finden Sie unter Apps registrieren und API verwalten Schlüssel. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Edge hat einen API-Schlüssel erhalten, der gültig ist. aber nicht mit einem freigegebenen Schlüssel in der Entwickler-App, die über ein Produkt mit Ihrem API-Proxy verknüpft ist. |
Bereitstellungsfehler
Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.
Fehlername | Ursache |
---|---|
SpecifyValueOrRefApiKey |
Für das Element <APIKey> wurde kein Wert oder Schlüssel angegeben. |
Fehlervariablen
Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.
Variablen | Wo | Beispiel |
---|---|---|
fault.name="fault_name" |
fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. | oauthV2.VK-VerifyAPIKey.failed = true |
Beispiele für Fehlerantworten
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
Beispiel für eine Fehlerregel
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>