Ein https.onCall
Trigger für Cloud Functions ist ein HTTPS-Trigger mit einem bestimmten Format für Anfrage und Antwort. Dieser Abschnitt enthält eine Spezifikation für die HTTPS-Anforderungs- und -Antwortformate, die von den Client-SDKs zur Implementierung der API verwendet werden. Diese Informationen können für Sie nützlich sein, wenn Ihre Anforderungen mit den Android-, Apple-Plattformen oder Web-SDKs nicht erfüllt werden können.
Anforderungsformat: Kopfzeilen
Die HTTP-Anforderung an einen aufrufbaren Trigger-Endpunkt muss ein POST
mit den folgenden Headern sein:
- Erforderlich:
Content-Type: application/json
- Ein optionales
; charset=utf-8
ist erlaubt.
- Ein optionales
- Optional:
Authorization: Bearer <token>
- Ein Benutzer-ID-Token für die Firebase-Authentifizierung für den angemeldeten Benutzer, der die Anfrage stellt. Das Back-End verifiziert dieses Token automatisch und stellt es im
context
des Handlers zur Verfügung . Wenn das Token nicht gültig ist, wird die Anfrage abgelehnt.
- Ein Benutzer-ID-Token für die Firebase-Authentifizierung für den angemeldeten Benutzer, der die Anfrage stellt. Das Back-End verifiziert dieses Token automatisch und stellt es im
- Optional:
Firebase-Instance-ID-Token: <iid>
- Das FCM-Registrierungstoken aus dem Firebase-Client-SDK. Dies muss eine Zeichenfolge sein. Dies ist im
context
des Handlers verfügbar. Es wird für das Targeting von Push-Benachrichtigungen verwendet.
- Das FCM-Registrierungstoken aus dem Firebase-Client-SDK. Dies muss eine Zeichenfolge sein. Dies ist im
- 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 dekodiert es, indem es die
appId
in dencontext
des Handlers einfügt. Wenn das Token nicht verifiziert werden kann, wird die Anfrage abgelehnt. (Verfügbar für SDK >=3.14.0)
- 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 dekodiert es, indem es die
Wenn andere Header enthalten sind, wird die Anforderung zurückgewiesen, wie in der Antwortdokumentation unten beschrieben.
Hinweis: In JavaScript-Clients lösen diese Anfragen einen CORS OPTIONS
Preflight aus, weil:
-
application/json
ist nicht zulässig. Es musstext/plain
oderapplication/x-www-form-urlencoded
sein. - Der
Authorization
Header ist kein CORS-safelisted request-header . - Andere Header sind ebenfalls nicht erlaubt.
Der aufrufbare Trigger verarbeitet diese OPTIONS
Anforderungen automatisch.
Anforderungstext
Der Hauptteil der HTTP-Anforderung sollte ein JSON-Objekt mit einem der folgenden Felder sein:
- Erforderlich:
data
- Das an die Funktion übergebene Argument. Dies kann ein beliebiger gültiger JSON-Wert sein. Dies wird gemäß dem unten beschriebenen Serialisierungsformat automatisch in native JavaScript-Typen dekodiert.
Wenn die Anfrage andere Felder enthält, betrachtet das Back-End die Anfrage als fehlerhaft und 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 Falle eines HTTP-Fehlers, bevor der
client
Trigger aufgerufen wird, wird die Antwort nicht als Client-Funktion behandelt. Wenn ein Client beispielsweise versucht, eine nicht vorhandene Funktion aufzurufen, erhält er die Antwort404 Not Found
.Wenn der Client-Trigger aufgerufen wird, aber die Anfrage das falsche Format hat, z. B. kein JSON-Format ist, ungültige Felder enthält oder das
data
fehlt, wird die Anfrage mit400 Bad Request
und dem FehlercodeINVALID_ARGUMENT
zurückgewiesen.Wenn das in der Anforderung angegebene Authentifizierungstoken ungültig ist, wird die Anforderung mit
401 Unauthorized
und dem FehlercodeUNAUTHENTICATED
abgelehnt.Wenn das in der Anforderung angegebene FCM-Registrierungstoken ungültig ist, ist das Verhalten nicht definiert. Das Token wird nicht bei jeder Anfrage überprüft, außer wenn es zum Senden einer Push-Benachrichtigung mit FCM verwendet wird.
Wenn der aufrufbare Trigger aufgerufen wird, aber mit einer nicht behandelten Ausnahme fehlschlägt oder ein fehlgeschlagenes Promise zurückgibt, wird die Anforderung mit
500 Internal Server Error
und dem FehlercodeINTERNAL
zurückgewiesen. Dadurch wird verhindert, dass Endbenutzern versehentlich Codierungsfehler offengelegt werden.Wenn die aufrufbare Funktion aufgerufen wird und mithilfe der für aufrufbare Funktionen bereitgestellten API eine explizite Fehlerbedingung zurückgibt, schlägt die Anforderung fehl. Der zurückgegebene HTTP-Statuscode basiert auf der offiziellen Zuordnung des Fehlerstatus zum HTTP-Status, wie in code.proto definiert. Der spezifische Fehlercode, die Nachricht und die zurückgegebenen Details sind im Antworttext codiert, wie unten beschrieben. Das bedeutet, wenn die Funktion einen expliziten Fehler mit dem Status
OK
zurückgibt, dann hat die Antwort den Status200 OK
, aber daserror
ist in der Antwort gesetzt.Wenn der Client-Trigger erfolgreich ist, lautet der Antwortstatus
200 OK
.
Antwortformat: Header
Die Antwort hat die folgenden Header:
-
Content-Type: application/json
- Ein optionales
; charset=utf-8
ist erlaubt.
Antworttext
Die Antwort von einem Client-Endpunkt ist immer ein JSON-Objekt. Es enthält mindestens entweder result
oder error
, zusammen mit optionalen Feldern. Wenn die Antwort kein JSON-Objekt ist oder keine data
oder error
enthält, sollte das Client-SDK die Anforderung 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 ob auchdata
vorhanden sind. Der Wert dieses Felds sollte ein JSON-Objekt im standardmäßigen Google Cloud-HTTP-Zuordnungsformat für Fehler sein, mit Feldern fürstatus
,message
und (optional)details
. Dascode
darf nicht enthalten sein. Wenn dasstatus
nicht gesetzt ist oder einen ungültigen Wert hat, sollte der Client den Status gemäß code.proto alsINTERNAL
behandeln. Wenndetails
vorhanden sind, sind sie gegebenenfalls in allen Benutzerinformationen enthalten, die an den Fehler im Client-SDK angehängt sind.
Hinweis: Dasdetails
hier ist ein vom Benutzer bereitgestellter Wert. Es ist nicht notwendigerweise eine Liste von Werten, die nach Prototyptyp codiert sind, wie im Google-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 Benutzer zurückgegebenen Wert automatisch in dieses JSON-Format. Die Client-SDKs decodieren diese Parameter gemäß dem unten beschriebenen Serialisierungsformat automatisch in native Typen.
Wenn andere Felder vorhanden sind, sollten sie ignoriert werden.
Serialisierung
Das Serialisierungsformat für beliebige Datennutzlasten ist sowohl für die Anfrage als auch für die Antwort dasselbe.
Aus Gründen der Plattformkonsistenz werden diese in JSON codiert, als ob sie der Wert eines Any
Felds in einem proto3-Protokollpuffer wären, wobei die standardmäßige 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 double
werden also auf die gleiche Weise codiert, und Sie wissen möglicherweise nicht, was am anderen Ende des Anrufs empfangen wird. Für Typen, die nicht in JSON nativ sind, wird die typisierte proto3-Codierung für den Wert verwendet. Weitere Informationen finden Sie in der Dokumentation für Beliebige JSON-Codierung .
Folgende Typen sind erlaubt:
- null -
null
- int (mit oder ohne Vorzeichen, bis zu 32 Bit) - zB
3
oder-30
. - Schwimmer - zB
3.14
- doppelt - zB
3.14
- boolean -
true
oderfalse
- Zeichenfolge - zB
"hello world"
- Karte
- zB {"x": 3}
- Liste
- zB [1, 2, 3]
- lang (mit oder ohne Vorzeichen, bis zu 64 Bit) - [Details siehe unten]
NaN
und Infinity
Werte für float
und double
werden nicht unterstützt.
Beachten Sie, dass long
ein spezieller Typ ist, der normalerweise in JSON nicht erlaubt ist, aber von der proto3-Spezifikation abgedeckt wird. Diese sind beispielsweise codiert als:
lang
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
unsigniert lang
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
Im Allgemeinen sollte der @type
Schlüssel als reserviert betrachtet und nicht für übergebene Maps verwendet werden.
Da der Typ für einfache Typen nicht angegeben ist, ändern einige Werte den Typ, nachdem sie über die Leitung geführt wurden. Ein übergebener float
wird zu einem double
. Ein short
wird zu einem int
und so weiter. In 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 @type
Feld deserialisiert wird, wird sie als Map belassen. Dadurch können Entwickler Felder mit neuen Typen zu ihren Rückgabewerten hinzufügen, ohne ältere Clients zu beschädigen.
Codebeispiele
Die Beispiele in diesem Abschnitt veranschaulichen, wie Folgendes codiert wird:
- Ein callable.call-Beispiel in Swift
- Eine Erfolgsantwort für den Anruf
- Eine Fehlerantwort für den Anruf
Callable.call-Beispiel in Swift zum Kodieren
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
Anforderungsheader:
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"
}
}
}
Antwort auf Codierung
return {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
};
Header erfolgreicher Antwort:
200 OK
Content-Type: application/json; charset=utf-8
Erfolgreicher Antworttext:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Fehlerantwort auf Codierung
throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
"some-key": "some-value"
});
Header für fehlgeschlagene Antwort:
401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8
Fehlerhafter Antworttext:
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}