Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Protokollspezifikation für https.onCall

Ein https.onCall-Trigger für Cloud Functions ist ein HTTPS-Trigger mit einem bestimmten Format für die Anfrage und die Antwort. In diesem Abschnitt finden Sie eine Spezifikation für die HTTPS-Anfrage- und Antwortformate, die von den Client-SDKs zur Implementierung der API verwendet werden. Diese Informationen können hilfreich sein, wenn Ihre Anforderungen mit den Android-, Apple- oder Web-SDKs nicht erfüllt werden können.

Anfrageformat: Header

Die HTTP-Anfrage an einen aufrufbaren Triggerendpunkt muss eine POST-Anfrage mit den folgenden Headern sein:

Erforderlich: Content-Type: application/json
- Optional ist ; charset=utf-8 zulässig.
Optional: Authorization: Bearer <token>
- Ein Firebase Authentication Nutzer-ID-Token für den angemeldeten Nutzer, der die Anfrage stellt. Das Back-End überprüft dieses Token automatisch und stellt es im context des Handlers zur Verfügung. Wenn das Token ungültig ist, wird die Anfrage abgelehnt.
Optional: Firebase-Instance-ID-Token: <iid>
- Das FCM-Registrierungstoken aus dem Firebase-Client-SDK. Dies muss ein String sein. Es ist im context des Handlers verfügbar. Es wird für Push-Benachrichtigungen verwendet.
Optional: X-Firebase-AppCheck: <token>
- Das Firebase App Check-Token, das von der Client-App bereitgestellt wird, die die Anfrage stellt. Das Back-End überprüft dieses Token automatisch und decodiert es, wobei die appId in den context des Handlers eingefügt wird. Wenn das Token nicht überprüft werden kann, wird die Anfrage abgelehnt. (Verfügbar für SDK >= 3.14.0)

Wenn andere Header enthalten sind, wird die Anfrage abgelehnt, wie in der Antwortdokumentation unten beschrieben.

Hinweis:In JavaScript-Clients lösen diese Anfragen einen CORS-OPTIONS-Preflight aus, weil:

application/json nicht zulässig ist. Es muss text/plain oder application/x-www-form-urlencoded sein.
Der Authorization Header ist kein CORS-Header, der auf der Zulassungsliste steht.
Andere Header sind ebenfalls nicht zulässig.

Der aufrufbare Trigger verarbeitet diese OPTIONS-Anfragen automatisch.

Anfragetext

Der Text der HTTP-Anfrage sollte ein JSON-Objekt mit einem der folgenden Felder sein:

Erforderlich: data – Das Argument, das an die Funktion übergeben wird. Dies kann ein beliebiger gültiger JSON-Wert sein. Er wird gemäß dem unten beschriebenen Serialisierungsformat automatisch in native JavaScript-Typen decodiert.

Wenn in der Anfrage andere Felder vorhanden sind, betrachtet das Back-End die Anfrage als fehlerhaft und sie wird abgelehnt.

Antwortformat: Statuscodes

Es gibt mehrere Fälle, die zu unterschiedlichen HTTP-Statuscodes und String-Statuscodes für Fehler in der Antwort führen können.

Im Fall eines HTTP-Fehlers, bevor der client-Trigger aufgerufen wird, wird die Antwort nicht als Clientfunktion behandelt. Wenn ein Client beispielsweise versucht, eine nicht vorhandene Funktion aufzurufen, erhält er die Antwort 404 Not Found.
Wenn der Client-Trigger aufgerufen wird, die Anfrage aber das falsche Format hat, z. B. kein JSON ist, ungültige Felder enthält oder das Feld data fehlt, wird die Anfrage mit 400 Bad Request und dem Fehlercode INVALID_ARGUMENT abgelehnt.
Wenn das in der Anfrage angegebene Authentifizierungstoken ungültig ist, wird die Anfrage mit 401 Unauthorized und dem Fehlercode UNAUTHENTICATED abgelehnt.
Wenn das in der Anfrage angegebene FCM-Registrierungstoken ungültig ist, ist das Verhalten nicht definiert. Das Token wird nicht bei jeder Anfrage überprüft, außer wenn damit eine Push-Benachrichtigung mit FCM gesendet wird.
Wenn der aufrufbare Trigger aufgerufen wird, aber mit einer nicht behandelten Ausnahme fehlschlägt oder ein fehlgeschlagenes Promise zurückgibt, wird die Anfrage mit 500 Internal Server Error und dem Fehlercode INTERNAL abgelehnt. So wird verhindert, dass Programmierfehler versehentlich für Endnutzer sichtbar werden.
Wenn der aufrufbare Trigger aufgerufen wird und eine explizite Fehlerbedingung über die API zurückgibt, die für aufrufbare Funktionen bereitgestellt wird, schlägt die Anfrage fehl. Der zurückgegebene HTTP-Statuscode basiert auf der offiziellen Zuordnung von Fehlerstatus zu HTTP-Status, wie in code.proto definiert. Der spezifische Fehlercode, die Nachricht und die zurückgegebenen Details werden wie unten beschrieben im Antworttext codiert. Wenn die Funktion also einen expliziten Fehler mit dem Status OK zurückgibt, hat die Antwort den Status 200 OK, aber das Feld error ist in der Antwort festgelegt.
Wenn der Client-Trigger erfolgreich ist, ist der Antwortstatus 200 OK.

Antwortformat: Header

Die Antwort hat die folgenden Header:

Content-Type: application/json
Optional ist ; charset=utf-8 zulässig.

Antworttext

Die Antwort von einem Clientendpunkt ist immer ein JSON-Objekt. Sie enthält mindestens result oder error sowie alle optionalen Felder. Wenn die Antwort kein JSON-Objekt ist oder data oder error nicht enthält, sollte das Client-SDK die Anfrage als fehlgeschlagen mit dem Google-Fehlercode INTERNAL (13) behandeln.

error – Wenn dieses Feld vorhanden ist, gilt die Anfrage als fehlgeschlagen, unabhängig vom HTTP-Statuscode oder davon, ob auch data vorhanden ist. Der Wert dieses Felds sollte ein JSON-Objekt im Standardformat für die HTTP-Zuordnung von Google Cloud für Fehler sein, mit Feldern für status, message und optional details. Das Feld code darf nicht enthalten sein. Wenn das Feld status nicht festgelegt ist oder einen ungültigen Wert hat, sollte der Client den Status gemäß code.proto als INTERNAL behandeln. Wenn details vorhanden ist, wird es gegebenenfalls in alle Nutzerinformationen aufgenommen, die dem Fehler im Client-SDK angehängt sind.
Hinweis:Das Feld details ist hier ein vom Nutzer angegebener Wert. Es ist nicht unbedingt eine Liste von Werten, die nach dem Protobuf-Typ mit einem Schlüssel versehen sind, wie im Google-Format Status.
result – Der von der Funktion zurückgegebene Wert. Dies kann ein beliebiger gültiger JSON-Wert sein. Das firebase-functions SDK codiert den vom Nutzer zurückgegebenen Wert automatisch in dieses JSON-Format. Die Client-SDKs decodieren diese Parameter gemäß dem unten beschriebenen Serialisierungsformat automatisch in native Typen.

Andere Felder sollten ignoriert werden.

Serialisierung

Das Serialisierungsformat für beliebige Daten-Nutzlasten ist für Anfrage und Antwort gleich.

Aus Gründen der Plattformkonsistenz werden diese in JSON codiert, als wären sie der Wert eines Any Felds in einem proto3-Protokollpuffer, wobei die Standard-JSON-Zuordnung verwendet wird. Werte einfacher Typen wie null, int, double oder string werden direkt codiert und enthalten nicht ihren expliziten Typ. Ein float und ein double werden also auf dieselbe Weise codiert und Sie wissen möglicherweise nicht, welcher Typ am anderen Ende des Aufrufs empfangen wird. Für Typen, die nicht nativ in JSON sind, wird die typisierte proto3-Codierung für den Wert verwendet. Weitere Informationen finden Sie in der Dokumentation zur JSON-Codierung von „Any“.

Die folgenden Typen sind zulässig:

null – null
int (mit oder ohne Vorzeichen, bis zu 32 Bit) – z.B. 3 oder -30.
float – z.B. 3.14
double – z.B. 3.14
boolean – true oder false
string – z.B. "hello world"
map<string, any=""> – z.B. {"x": 3}</string,>
list – z.B. [1, 2, 3]
long (mit oder ohne Vorzeichen, bis zu 64 Bit) – [Weitere Informationen finden Sie unten]

NaN- und Infinity-Werte für float und double werden nicht unterstützt.

long ist ein spezieller Typ, der normalerweise in JSON nicht zulässig ist, aber in der proto3-Spezifikation behandelt wird. Beispielsweise werden diese so codiert:

long

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

unsigned long

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

Im Allgemeinen sollte der Schlüssel @type als reserviert betrachtet und nicht für übergebene Maps verwendet werden.

Da der Typ für einfache Typen nicht angegeben ist, ändert sich der Typ einiger Werte nach der Übertragung. Ein übergebener float wird zu einem double. Ein short wird zu einem int usw. Unter Android werden sowohl List als auch JSONArray für Listenwerte unterstützt. In diesen Fällen ergibt die Übergabe eines JSONArray eine List.

Wenn eine Map mit einem unbekannten Feld @type deserialisiert wird, bleibt sie als Map erhalten. So können Entwickler ihren Rückgabewerten Felder mit neuen Typen hinzufügen, ohne ältere Clients zu beeinträchtigen.

Codebeispiele

Die Beispiele in diesem Abschnitt veranschaulichen, wie Folgendes codiert wird:

Ein Beispiel für callable.call in Swift
Eine Erfolgsantwort für den Aufruf
Eine Fehlerantwort für den Aufruf

Beispiel für callable.call in Swift zum Codieren

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

Anfrage-Header:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

Anfragetext:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

Zu codierende Antwort

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

Header der Erfolgsantwort:

200 OK
Content-Type: application/json; charset=utf-8

Text der Erfolgsantwort:

{
    "response": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

Zu codierende Fehlerantwort

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

Header der Fehlerantwort:

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

Text der Fehlerantwort:

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}