Mit binären Medientypen für REST-APIs arbeiten

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. Eine binäre Nutzlast kann beispielsweise eine JPEG-, GZip- oder 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.

AWS Lambda-Proxy-Integrationen

Um binäre Nutzlasten für AWS Lambda-Proxy-Integrationen zu verarbeiten, müssen Sie für die Antwort Ihrer Funktion base64-Codierung verwenden. Sie müssen auch die binaryMediaTypes für Ihre API konfigurieren. 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. */* enthält beispielsweise alle Inhaltstypen.

Beispielcode finden Sie unter Rückgabe binärer Medien von einer Lambda-Proxy-Integration.

Nicht-Proxy-Integrationen

Um binäre Nutzlasten für Nicht-Proxy-Integrationen zu verarbeiten, fügen Sie die Medientypen der Liste binaryMediaTypes der RestApi-Ressource hinzu. 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 IntegrationResponse-Ressourcen einstellen. Der Wert contentHandling kann CONVERT_TO_BINARY, CONVERT_TO_TEXT oder undefiniert sein.

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 Liste binaryMediaTypes der RestApi-Ressource 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 IntegrationResponse-Ressource 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.