Binäre Medientypen für REST APIs in API Gateway - Amazon API Gateway
AWS Lambda Proxy-IntegrationenNicht-Proxy-Integrationen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Binäre Medientypen für REST APIs in API Gateway

In API Gateway haben die API-Anfrage und -Antwort einen Text-Payload oder einen Binär-Payload. Eine Text-Nutzlast ist eine UTF-8-codierte JSON-Zeichenfolge. Eine binäre Nutzlast ist jede beliebige andere außer einer Text-Nutzlast. Die binäre Nutzlast kann beispielsweise eine JPEG-Datei, eine GZip Datei oder eine XML-Datei sein. Welche API-Konfiguration zur Unterstützung von binären Medien erforderlich ist, hängt davon ab, ob Ihre API Proxy- oder Nicht-Proxyintegrationen verwendet.

Wenn Sie eine Proxy-Integration mit Payload-Response-Streaming verwenden, müssen Sie Ihre binären Medientypen nicht konfigurieren. Weitere Informationen finden Sie unter Streamen Sie die Integrationsantwort für Ihre Proxy-Integrationen in API Gateway.

AWS Lambda Proxy-Integrationen

Um binäre Nutzlasten für AWS Lambda Proxy-Integrationen zu verarbeiten, müssen Sie die Antwort Ihrer Funktion base64-kodieren. Sie müssen das auch für Ihre API konfigurieren. binaryMediaTypes Die binaryMediaTypes-Konfiguration Ihrer API ist eine Liste von Inhaltstypen, die Ihre API als Binärdaten behandelt. Beispiele für binäre Medientypen umfassen image/png oder application/octet-stream. Sie können das Platzhalterzeichen (*) verwenden, um mehrere Medientypen abzudecken.

API Gateway verwendet den ersten Accept-Header von Clients, um zu bestimmen, ob eine Antwort binäre Medien zurückgeben soll. Um binäre Medien zurückzugeben, wenn Sie die Reihenfolge der Accept-Header-Werte nicht kontrollieren können, z. B. Anforderungen von einem Browser, setzen Sie die binären Medientypen der API auf */*.

Beispielcode finden Sie unter Rückgabe binärer Medien aus einer Lambda-Proxy-Integration in API Gateway.

Wenn Sie eine Lambda-Proxyintegration mit Payload Response-Streaming verwenden, müssen Sie Ihre binären Medientypen nicht konfigurieren. Weitere Informationen finden Sie unter Richten Sie eine Lambda-Proxy-Integration mit Payload-Response-Streaming in API Gateway ein.

Nicht-Proxy-Integrationen

Um binäre Payloads für Nicht-Proxy-Integrationen zu verarbeiten, fügen Sie die Medientypen der Liste der Ressource hinzu. binaryMediaTypesRestApi Die binaryMediaTypes-Konfiguration Ihrer API ist eine Liste von Inhaltstypen, die Ihre API als Binärdaten behandelt. Alternativ können Sie die ContentHandling-Eigenschaften für die Integration und die IntegrationResponseRessourcen festlegen. Der Wert contentHandling kann CONVERT_TO_BINARY, CONVERT_TO_TEXT oder undefiniert sein.

Anmerkung

Für MOCK oder private Integrationen wird das Festlegen der contentHandling-Eigenschaften in der AWS-Managementkonsole nicht unterstützt. Sie müssen das AWS CLI, oder ein SDK verwenden CloudFormation, um die contentHandling Eigenschaften festzulegen.

Je nach contentHandling-Wert sowie abhängig von der Tatsache, ob der Content-Type-Header der Antwort oder der Accept-Header der eingehenden Anfrage mit einem Eintrag in der Liste binaryMediaTypes übereinstimmt, kann Amazon API Gateway die unformatierten binären Bytes als base64-kodierte Zeichenfolge kodieren, eine base64-kodierte Zeichenfolge zurück in die Raw-Bytes dekodieren oder den Textkörper ohne Änderung weitergeben.

Um binäre Payloads für Ihre API in API Gateway zu unterstützen, müssen Sie die API wie folgt konfigurieren:

  • Fügen Sie die gewünschten binären Medientypen zur binaryMediaTypes Liste auf der RestApiRessource hinzu. Wenn diese Eigenschaft und die contentHandling-Eigenschaft nicht definiert sind, werden die Nutzlasten als UTF-8-kodierte JSON-Zeichenfolgen verarbeitet.

  • Legen Sie die Eigenschaft contentHandling der Ressource Integration fest.

    • Damit die Anforderungsnutzlast von einer Base64-kodierten Zeichenfolge in ihr binäres Blob konvertiert wird, setzen Sie die Eigenschaft auf CONVERT_TO_BINARY.

    • Damit die Anforderungsnutzlast von einem binären Blob in eine Base64-codierte Zeichenfolge konvertiert wird, setzen Sie die Eigenschaft auf CONVERT_TO_TEXT.

    • Um die Nutzlast ohne Änderung zu übergeben, lassen Sie die Eigenschaft undefiniert. Um eine binäre Nutzlast ohne Änderung zu übergeben, müssen Sie auch sicherstellen, dass der Content-Type mit einem der binaryMediaTypes-Einträge übereinstimmt und Passthrough-Verhalten für die API aktiviert sind.

  • Legen Sie die contentHandling Eigenschaft der IntegrationResponseRessource fest. Die contentHandling-Eigenschaft, der Accept-Header in Client-Anfragen und die binaryMediaTypes Ihrer APIs legen zusammen fest, wie API Gateway Inhaltstypkonvertierungen handhabt. Details hierzu finden Sie unter Inhaltstypkonvertierungen in API Gateway.

Wichtig

Wenn eine Anfrage mehrere Medientypen in ihrem Accept-Header enthält, berücksichtigt API Gateway nur den ersten Accept-Medientyp. Wenn Sie die Reihenfolge der Accept-Medientypen nicht beeinflussen können und der Medientyp Ihres binären Inhalts nicht der erste in der Liste ist, fügen Sie den ersten Accept-Medientyp in der binaryMediaTypes-Liste Ihrer API hinzu. API Gateway behandelt alle Inhaltstypen in dieser Liste als binär.

Um z. B. eine JPEG-Datei mit einem <img>-Element in einem Browser zu übermitteln, sendet der Browser möglicherweise Accept:image/webp,image/*,*/*;q=0.8 in einer Anforderung. Bei Hinzufügen von image/webp zur Liste binaryMediaTypes erhält der Endpunkt die JPEG-Datei als Binärdatei.

Ausführliche Informationen darüber, wie API Gateway die Text- und Binär-Payloads behandelt, finden Sie unter Inhaltstypkonvertierungen in API Gateway.