Einrichten von Stufenvariablen für eine REST-API-Bereitstellung

Bei Stufenvariablen handelt es sich um Namen-Wert-Paare, die Sie als Konfigurationsattribute für eine REST-API-Bereitstellungsstufe definieren können. Sie weisen dasselbe Verhalten auf wie Umgebungsvariablen und können für die API-Einrichtung und Mapping-Vorlagen verwendet werden.

Sie können beispielsweise in einer Stufenkonfiguration eine Stufenvariable definieren und dann deren Wert als URL-Zeichenfolge einer HTTP-Integration für eine Methode in Ihrer REST-API festlegen. Später können Sie mithilfe des zugehörigen Stufenvariablennamens (aus der API-Einrichtung) auf die URL-Zeichenfolge verweisen. Auf diese Weise können Sie dieselbe API-Einrichtung mit einem anderen Endpunkt für jede Stufe verwenden, indem Sie den Stufenvariablenwert auf die entsprechenden URLs setzen.

Sie können auch auf Stufenvariablen in Mapping-Vorlagen zugreifen oder Konfigurationsparameter an das AWS Lambda- oder das HTTP-Backend übergeben.

Weitere Informationen zu Mapping-Vorlagen finden Sie unter Referenz zu API Gateway-Mapping-Vorlage und -Zugriffsprotokollierungsvariablen.

Anmerkung

Stage-Variablen sind nicht dazu gedacht, für sensible Daten wie Anmeldeinformationen verwendet zu werden. Um sensible Daten an Integrationen weiterzugeben, verwenden Sie einen AWS Lambda-Genehmiger. Sie können sensible Daten an Integrationen in der Ausgabe des Lambda-Genehmigers übergeben. Weitere Informationen hierzu finden Sie unter Ausgabe von einem Amazon API Gateway-Lambda-Genehmiger.

Anwendungsfälle

Mit den Bereitstellungsstufen in API Gateway können Sie für jede API mehrere Freigabestufen verwalten (z. B. „Alpha“, „Beta“ und „Produktion“). Über die Stufenvariablen können Sie eine API-Bereitstellungsstufe für die Interaktion mit verschiedenen Backend-Endpunkten konfigurieren.

Ihre API kann beispielsweise eine GET-Anforderung als HTTP-Proxy an den Backend-Webhost übergeben (z. B, http://example.com). Dabei wird der Backend-Webhost in einer Stufenvariable konfiguriert, so dass API Gateway „example.com“ aufruft, wenn Entwickler Ihren Produktionsendpunkt aufrufen. Wird der Beta-Endpunkt aufgerufen, verwendet API Gateway den in der Stufenvariable für die Beta-Stufe konfigurierten Wert und ruft einen anderen Webhost auf (z. B, beta.example.com). Ebenso lässt sich über Stufenvariablen für jede Stufe Ihrer API ein anderer AWS Lambda-Funktionsname angeben.

Sie können auch Stufenvariablen verwenden, um Konfigurationsparameter über Mapping-Vorlagen an eine Lambda-Funktion zu übergeben. Beispielsweise können Sie die gleiche Lambda-Funktion für mehrere Stufen der API nutzen, jedoch soll die Funktion abhängig von der aufgerufenen Stufe jeweils Daten aus einer anderen Amazon DynamoDB-Tabelle lesen. In den Mapping-Vorlagen, von denen die Anforderung für die Lambda-Funktion generiert wird, können Sie den Tabellennamen mit Stufenvariablen an Lambda übergeben.

Beispiele

Damit Sie eine Stufenvariable zur Anpassung des HTTP-Integrationsendpunkts verwenden können, müssen Sie zunächst eine Stufenvariable für einen bestimmten Namen (z. B. url) konfigurieren und diesem einen Wert zuweisen (z. B. example.com). Richten Sie als Nächstes in Ihrer Methodenkonfiguration eine HTTP-Proxy-Integration ein. Anstatt die URL des Endpunkts einzugeben, können Sie API Gateway anweisen, den Wert der Stufenvariablen zu verwenden, http://${stageVariables.url}. Mit diesem Wert wird API Gateway angewiesen, die Stufenvariable ${} zur Laufzeit abhängig von der ausgeführten API-Stufe zu ersetzen.

Sie können Stufenvariablen auf die gleiche Weise referenzieren, um einen Lambda-Funktionsnamen, einen AWS-Service-Proxy-Pfad oder einen AWS-Rollen-ARN im Feld für die Anmeldeinformationen anzugeben.

Wenn Sie einen Lambda-Funktionsnamen als Stufenvariablenwert angeben, müssen Sie die Berechtigungen für die Lambda-Funktion manuell konfigurieren. Wenn Sie eine Lambda-Funktion in der API-Gateway-Konsole angeben, wird ein AWS CLI-Befehl zur Konfiguration der richtigen Berechtigungen angezeigt. Sie können auch die AWS Command Line Interface (AWS CLI) dafür verwenden.

aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction