Einführung in das Testen mit sam local start-api

Verwenden Sie den AWS Serverless Application Model sam local start-api Unterbefehl Command Line Interface (AWS SAMCLI), um Ihre AWS Lambda Funktionen lokal auszuführen und über einen lokalen HTTP-Serverhost zu testen. Diese Art von Test ist hilfreich für Lambda-Funktionen, die von einem Amazon API Gateway Gateway-Endpunkt aufgerufen werden.

• Eine Einführung in das finden Sie unter AWS SAMCLI. Was ist das? AWS SAMCLI

• Eine Liste der sam local start-api Befehlsoptionen finden Sie untersam local start-api.

• Ein Beispiel für die Verwendung sam local start-api während eines typischen Entwicklungsworkflows finden Sie unterSchritt 7: (Optional) Testen Sie Ihre Anwendung lokal.

Voraussetzungen

Um das zu verwendensam local start-api, installieren Sie das, AWS SAMCLI indem Sie wie folgt vorgehen:

• AWS SAM Voraussetzungen.

• Installiere das AWS SAMCLI.

Vor der Verwendung empfehlen wirsam local start-api, sich mit folgenden Grundkenntnissen vertraut zu machen:

• Konfiguration der AWS SAMCLI.

• Erstellen Sie Ihre Anwendung mit dem sam init Befehl.

• Einführung in das Bauen mit dem sam build Befehl.

• Einführung in die Bereitstellung mit dem sam deploy Befehl.

Verwenden Sie dieselbe lokale Start-API

Beim Ausführen AWS SAMCLI geht das davon aussam local start-api, dass Ihr aktuelles Arbeitsverzeichnis das Stammverzeichnis Ihres Projekts ist. Das AWS SAMCLI sucht zuerst nach einer template.[yaml|yml] Datei in einem .aws-sam Unterordner. Wenn nicht gefunden, sucht der AWS SAMCLI nach einer template.[yaml|yml] Datei in Ihrem aktuellen Arbeitsverzeichnis.

Um einen lokalen HTTP-Server zu starten

1. Führen Sie im Stammverzeichnis Ihres Projekts Folgendes aus:

   $ sam local start-api <options>

2. Das AWS SAMCLI erstellt Ihre Lambda-Funktionen in einem lokalen Docker Container. Anschließend wird die lokale Adresse Ihres HTTP-Serverendpunkts ausgegeben. Im Folgenden wird ein Beispiel gezeigt:

   $ sam local start-api
   
   Initializing the lambda functions containers.
   Local image is up-to-date
   Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.
   
   Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
   Containers Initialization is done.
   Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
   You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
   2023-04-12 14:41:05 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
    * Running on http://127.0.0.1:3000

3. Sie können Ihre Lambda-Funktion über den Browser oder die Befehlszeile aufrufen. Im Folgenden wird ein Beispiel gezeigt:

   sam-app$ curl http://127.0.0.1:3000/hello
   {"message": "Hello world!"}%

4. Wenn Sie Änderungen an Ihrem Lambda-Funktionscode vornehmen, sollten Sie Folgendes beachten, um Ihren lokalen HTTP-Server zu aktualisieren:

   • Wenn Ihre Anwendung kein .aws-sam Verzeichnis hat und Ihre Funktion eine interpretierte Sprache verwendet, aktualisiert sie Ihre Funktion AWS SAMCLI automatisch, indem sie einen neuen Container erstellt und diesen hostet.

   • Wenn Ihre Anwendung über ein .aws-sam Verzeichnis verfügt, müssen Sie ausführen, sam build um Ihre Funktion zu aktualisieren. Führen Sie dann sam local start-api erneut aus, um die Funktion zu hosten.

   • Wenn Ihre Funktion eine kompilierte Sprache verwendet oder wenn Ihr Projekt komplexe Paketierungsunterstützung erfordert, führen Sie Ihre eigene Build-Lösung aus, um Ihre Funktion zu aktualisieren. Führen Sie dann sam local start-api erneut aus, um die Funktion zu hosten.

Lambda-Funktionen, die Lambda-Autorisierer verwenden

Anmerkung

Diese Funktion ist neu in Version 1.80.0. AWS SAMCLI Informationen zum Upgrade finden Sie unter Aktualisierung des AWS SAMCLI.

Bei Lambda-Funktionen, die Lambda-Autorisierer verwenden, rufen sie AWS SAMCLI automatisch Ihren Lambda-Autorisierer auf, bevor Sie Ihren Lambda-Funktionsendpunkt aufrufen.

Im Folgenden finden Sie ein Beispiel für das Starten eines lokalen HTTP-Servers für eine Funktion, die einen Lambda-Authorizer verwendet:

$ sam local start-api
2023-04-17 15:02:13 Attaching import module proxy for analyzing dynamic imports

AWS SAM CLI does not guarantee 100% fidelity between authorizers locally
and authorizers deployed on AWS. Any application critical behavior should
be validated thoroughly before deploying to production.

Testing application behaviour against authorizers deployed on AWS can be done using the sam sync command.

Mounting HelloWorldFunction at http://127.0.0.1:3000/authorized-request [GET]
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
2023-04-17 15:02:13 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:3000
2023-04-17 15:02:13 Press CTRL+C to quit

Wenn Sie Ihren Lambda-Funktionsendpunkt über den lokalen HTTP-Server aufrufen, ruft der AWS SAMCLI erste Ihren Lambda-Authorizer auf. Wenn die Autorisierung erfolgreich ist, AWS SAMCLI wird der Endpunkt Ihrer Lambda-Funktion aufgerufen. Im Folgenden wird ein Beispiel gezeigt:

$ curl http://127.0.0.1:3000/authorized-request --header "header:my_token"
{"message": "from authorizer"}%

Invoking app.authorizer_handler (python3.8)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0 Version: $LATEST
END RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0
REPORT RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0    Init Duration: 1.08 ms    Duration: 628.26 msBilled Duration: 629 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
Invoking app.request_handler (python3.8)
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: fdc12255-79a3-4365-97e9-9459d06446ff Version: $LATEST
END RequestId: fdc12255-79a3-4365-97e9-9459d06446ff
REPORT RequestId: fdc12255-79a3-4365-97e9-9459d06446ff    Init Duration: 0.95 ms    Duration: 659.13 msBilled Duration: 660 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
No Content-Type given. Defaulting to 'application/json'.
2023-04-17 15:03:03 127.0.0.1 - - [17/Apr/2023 15:03:03] "GET /authorized-request HTTP/1.1" 200 -

Optionen

Kontinuierliche Wiederverwendung von Containern zur Beschleunigung lokaler Funktionsaufrufe

Standardmäßig AWS SAMCLI erstellt der jedes Mal, wenn Ihre Funktion über den lokalen HTTP-Server aufgerufen wird, einen neuen Container. Verwenden Sie die --warm-containers Option, um Ihren Container automatisch für Funktionsaufrufe wiederzuverwenden. Dies beschleunigt die Zeit, die benötigt wird, AWS SAMCLI um Ihre Lambda-Funktion für den lokalen Aufruf vorzubereiten. Sie können diese Option weiter anpassen, indem Sie das Argument eager oder lazy angeben.

• eager— Container für alle Funktionen werden beim Start geladen und bleiben zwischen Aufrufen bestehen.

• lazy— Container werden nur geladen, wenn jede Funktion zum ersten Mal aufgerufen wird. Sie bleiben dann für weitere Aufrufe bestehen.

Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --warm-containers eager

Wenn Sie Ihren Lambda-Funktionscode verwenden --warm-containers und ändern:

• Wenn Ihre Anwendung über ein .aws-sam Verzeichnis verfügt, führen Sie sam build den Befehl aus, um Ihren Funktionscode in den Build-Artefakten Ihrer Anwendung zu aktualisieren.

• Wenn eine Codeänderung erkannt wird, wird der Lambda-Funktionscontainer AWS SAMCLI automatisch heruntergefahren.

• Wenn Sie die Funktion erneut aufrufen, erstellt der AWS SAMCLI automatisch einen neuen Container.

Geben Sie ein Container-Image an, das für Ihre Lambda-Funktionen verwendet werden soll

Standardmäßig AWS SAMCLI verwendet der Lambda-Basisimages aus Amazon Elastic Container Registry (Amazon ECR), um Ihre Funktionen lokal aufzurufen. Verwenden Sie die --invoke-image Option, um auf ein benutzerdefiniertes Container-Image zu verweisen. Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --invoke-image public.ecr.aws/sam/emu-python3.8

Sie können die Funktion angeben, die mit dem benutzerdefinierten Container-Image verwendet werden soll. Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --invoke-image Function1=amazon/aws/sam-cli-emulation-image-python3.8

Geben Sie eine Vorlage an, die lokal getestet werden soll

Verwenden Sie die --template Option, AWS SAMCLI um eine Vorlage anzugeben, auf die verwiesen werden soll. Es AWS SAMCLI werden nur diese AWS SAM Vorlage und die Ressourcen, auf die sie verweist, geladen. Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --template myTemplate.yaml

Geben Sie die Host-Entwicklungsumgebung Ihrer Lambda-Funktion an

Standardmäßig erstellt der sam local start-api Unterbefehl einen HTTP-Server localhost mit IP-Adresse. 127.0.0.1 Sie können diese Werte anpassen, wenn Ihre lokale Entwicklungsumgebung von Ihrem lokalen Computer isoliert ist.

Verwenden Sie die --container-host Option, um einen Host anzugeben. Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --container-host host.docker.internal

Verwenden Sie die --container-host-interface Option, um die IP-Adresse des Host-Netzwerks anzugeben, an das Container-Ports gebunden werden sollen. Im Folgenden wird ein Beispiel gezeigt:

$ sam local start-api --container-host-interface 0.0.0.0

Bewährte Methoden

Wenn Ihre Anwendung ein .aws-sam Verzeichnis hat, das nicht ausgeführt wirdsam build, stellen Sie sicher, dass es sam build jedes Mal ausgeführt wird, wenn Sie Ihren Funktionscode aktualisieren. Führen Sie dann sam local start-api die Ausführung aus, um Ihren aktualisierten Funktionscode lokal zu testen.

Lokales Testen ist eine hervorragende Lösung für schnelles Entwickeln und Testen vor der Bereitstellung in der Cloud. Bei lokalen Tests wird jedoch nicht alles überprüft, z. B. die Berechtigungen zwischen Ihren Ressourcen in der Cloud. Testen Sie Ihre Anwendungen so oft wie möglich in der Cloud. Wir empfehlen sam sync die Verwendung, um Ihre Cloud-Test-Workflows zu beschleunigen.

Weitere Informationen

Eine Liste aller sam local start-api Optionen finden Sie untersam local start-api.