Wie ordne ich die Antwortstatuscodes für API-Gateway-Integrationen in REST-APIs zu?

Auflösung

Wenn Sie Ihre Backend-Antwortstatuscodes außer Kraft setzen möchten, verwenden Sie API-Gateway-Zuordnungsvorlagen oder reguläre Ausdrücke, um die Statuscodes zuzuordnen. Sie können dies in Proxy- und Nicht-Proxy-Integrationen mit der REST-API tun.

Proxy- und Nicht-Proxy-Integrationen werden verwendet, um Antwortstatuscodes in der REST-API. Wenn es eine Proxy-Antwort gibt, empfängt API Gateway die Statuscodes so, wie sie vom Backend gesendet werden. In einer Lambda-Proxy-Integration benötigt API Gateway die Backend-Lambda-Funktion, um die folgende Ausgabe im JSON-Format zurückzugeben:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

Bei einer Proxy-Integration mit einer Lambda-Funktion wird ein Statuscode von einer Backend-Lambda-Funktion direkt an API Gateway übergeben. Ein Statuscode kann in einer Nicht-Proxy-Integration nicht direkt von der Lambda-Funktion übergeben werden.

Wenn API Gateway erfolgreich eine Lambda-Funktion aufruft, lautet der Standardantwortstatuscode 200. Statuscodes werden auch zurückgegeben, wenn bei Lambda Fehler auftreten. Sie können API-Gateway-Antwortcodes anpassen. Verwenden Sie eine Nicht-Proxy-Integration und eine Zuordnungsvorlage, wenn Sie einen benutzerdefinierten Antwortcode erstellen müssen.

Konfiguration einer Antwortmethode mit benutzerdefiniertem Code

Führen Sie die folgenden Schritte aus, um eine Methode zum Antworten mit benutzerdefiniertem Antwortcode von API Gateway zu konfigurieren:

1.    Erstellen Sie in der API-Gateway-Konsole eine öffentliche REST-API.

2.    Erstellen Sie eine Ressource und eine Methode für die Ressource.

3.    Richten Sie eine Methodenantwort ein, die den Statuscode enthält, den API Gateway zurückgeben soll.

4.    Konfigurieren Sie eine Lambda-Integrationsantwort.

• Geben Sie für Lambda Error Regex das Muster für reguläre Ausdrücke für die Fehlermeldung an, die von der Lambda-Funktion zurückgegeben wird.
  Hinweis: Sie können auch die HTTP-Fehler-Regex für HTTP-Antworten finden.
• Geben Sie für den Status der Methodenantwort den Statuscode an, der vom API Gateway zurückgegeben werden muss.
• Wählen Sie eine Option für Content Handling, um festzulegen, wie der Antworttext behandelt wird, bevor die Antwort an den Client gesendet wird.
• Stellen Sie sicher, dass das Standardmuster des Statuscodes auf 200 eingestellt ist.

5.    Nachdem Sie die Konfiguration Ihrer Integrationsantwort abgeschlossen haben, speichern, testen und implementieren Sie Ihre Änderungen.

Zuordnen von Statuscodes zu statischen Werten

Damit API Gateway eine Gruppe von Statuscodes erfassen kann, die von Ihrem Backend zurückgegeben wurden, ordnen Sie die Statuscodes statischen Werten zu:

1.    Gehen Sie zu der Ressource mit dem Statuscode, den Sie ändern möchten.

2.    Richten Sie eine Methodenantwort ein, um 400 als API-Gateway-Antwortcode zurückzugeben.

3.    Kehren Sie zu den Ressourcenkonfigurationen zurück und richten Sie eine Integrationsantwort ein.

4.    Die Werte im HTTP-Status-Regex erfassen den von Ihrem Backend zurückgegebenen Status. Der Status wird dann dem in Schritt 2 definierten Antwortcode zugeordnet.

Wenn der HTTP-Status Regex den Standardwert „-“ hat und 200 als Methodenantwortstatus zugeordnet ist, werden alle Statuscodes erfasst und von Ihrer Backend-Map an 200 zurückgegeben. Sie können die HTTP-Status-Regex-Werte in 2\d{2} ändern, um alle 2xx-Antworten zu erfassen und sie 200 zuzuordnen.

5.    Wählen Sie Integrationsantwort hinzufügen, um die anderen Statuscodes zu erfassen.

Für 4xx fügen Sie im HTTP-Status-Regex 4\d{2} hinzu. Wählen Sie für Methodenantwortstatus die Option 400. Dies wurde in Schritt 2 definiert.

6.    Stellen Sie Ihre API bereit. Wenn die API 2xx-Statuscodes zurückgibt, werden sie dem 200-Statuscode zugeordnet. Wenn Ihre API 4xx-Statuscodes zurückgibt, werden diese dem 400-Statuscode zugeordnet.

Reguläre Ausdrücke können auf verschiedene Arten formatiert werden. Beispiel:

• .* ([01] [0-9] [0-9] |2 [0-4] [0-9] |25 [0-5]) .* stimmt mit Statuscodes zwischen 100-199, 200-249 oder 250-255 überein.
• .*5\d\d.* stimmt mit einem Statuscode überein, z. B. 5xx.

Der folgende Beispielcode dient zum Testen einer Lambda-Funktion:

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

Im Beispiel überprüft der Code, ob der vom API Gateway gesendete Fehlerwert ein 400- oder 500-Fehler ist. Wenn es sich um einen 400- oder 500-Fehler handelt, löst der Lambda-Code eine Ausnahme mit einer Fehlermeldung aus. Wenn API Gateway die Antwort empfängt, überprüft der Service, ob die Fehlermeldung mit einem in der Integrationsantwort konfigurierten Muster übereinstimmt. API Gateway reagiert entsprechend, wenn das Lambda-Regex-Muster übereinstimmt.

7.    Nach einer erfolgreichen Konfiguration können die Statuscodes mit der API-Gateway-Konsole getestet werden.

Zuordnen von Statuscodes mit Zuordnungsvorlagen

Im vorherigen Beispiel werden reguläre Ausdrücke verwendet, es können aber auch Mapping-Vorlagen verwendet werden. Das folgende Beispiel überschreibt den 200-Statuscode aus dem Backend, um den 400-Statuscode anzuwenden:

1.    Erstellen Sie eine Lambda-Funktion mit folgendem Beispielcode:

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    Erstellen Sie eine API mit Lambda-Nicht-Proxy-Integration, indem Sie die vorherige Lambda-Funktion für das Backend verwenden.

3.    Folgen Sie den Schritten 6-10, die im Tutorial Überschreiben des Antwortstatuscodes einer API mit der API-Gateway-Konsole beschrieben sind.

Verwenden Sie in diesem Beispiel die folgende Mapping-Vorlage:

----------------------
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("customerror"))
#set($context.responseOverride.status = 400)
#end 
----------------------

4.    Speichern, testen und implementieren Sie die API.

---

Relevante Informationen

Arbeiten mit Modellen und Mapping-Vorlagen

Transformieren von API-Anforderungen und Antworten

Amazon API Gateway – Entwicklerhandbuch