Un trigger https.onCall
per Cloud Functions è un trigger HTTPS con un formato specifico per la richiesta e la risposta. Questa sezione fornisce una specifica per i formati di richiesta e risposta HTTPS utilizzati dagli SDK client per implementare l'API. Queste informazioni potrebbero esserti utili se i tuoi requisiti non possono essere soddisfatti utilizzando le piattaforme Android, Apple o gli SDK Web.
Formato della richiesta: intestazioni
La richiesta HTTP a un endpoint trigger richiamabile deve essere un POST
con le seguenti intestazioni:
- Obbligatorio:
Content-Type: application/json
- Un facoltativo
; charset=utf-8
è consentito.
- Un facoltativo
- Facoltativo:
Authorization: Bearer <token>
- Un token ID utente di autenticazione Firebase per l'utente che ha effettuato l'accesso che effettua la richiesta. Il backend verifica automaticamente questo token e lo rende disponibile nel
context
del gestore. Se il token non è valido, la richiesta viene rifiutata.
- Un token ID utente di autenticazione Firebase per l'utente che ha effettuato l'accesso che effettua la richiesta. Il backend verifica automaticamente questo token e lo rende disponibile nel
- Facoltativo:
Firebase-Instance-ID-Token: <iid>
- Il token di registrazione FCM dall'SDK del client Firebase. Deve essere una stringa. Questo è disponibile nel
context
del gestore. Viene utilizzato per indirizzare le notifiche push.
- Il token di registrazione FCM dall'SDK del client Firebase. Deve essere una stringa. Questo è disponibile nel
- Facoltativo:
X-Firebase-AppCheck: <token>
- Il token Firebase App Check fornito dall'app client che effettua la richiesta. Il backend verifica automaticamente questo token e lo decodifica, inserendo l'
appId
nelcontext
del gestore. Se il token non può essere verificato, la richiesta viene rifiutata. (Disponibile per SDK >=3.14.0)
- Il token Firebase App Check fornito dall'app client che effettua la richiesta. Il backend verifica automaticamente questo token e lo decodifica, inserendo l'
Se vengono incluse altre intestazioni, la richiesta viene rifiutata, come descritto nella documentazione di risposta di seguito.
Nota: nei client JavaScript, queste richieste attivano un preflight CORS OPTIONS
, perché:
-
application/json
non è consentito. Deve esseretext/plain
oapplication/x-www-form-urlencoded
. - L'intestazione
Authorization
non è un'intestazione richiesta inclusa nell'elenco di sicurezza CORS . - Allo stesso modo non sono consentite altre intestazioni.
Il trigger richiamabile gestisce automaticamente queste richieste OPTIONS
.
Richiedi corpo
Il corpo della richiesta HTTP deve essere un oggetto JSON con uno dei seguenti campi:
- Obbligatorio:
data
- L'argomento passato alla funzione. Può essere qualsiasi valore JSON valido. Questo viene decodificato automaticamente in tipi JavaScript nativi in base al formato di serializzazione descritto di seguito.
Se nella richiesta sono presenti altri campi, il backend considera la richiesta non valida e viene rifiutata.
Formato della risposta: codici di stato
Esistono diversi casi che potrebbero comportare codici di stato HTTP e codici di stato stringa diversi per errori nella risposta.
Nel caso di un errore HTTP prima che venga richiamato il trigger
client
, la risposta non viene gestita come una funzione client. Ad esempio, se un client tenta di richiamare una funzione inesistente, riceve una risposta404 Not Found
.Se il trigger client viene richiamato, ma la richiesta è nel formato sbagliato, ad esempio non è JSON, contiene campi non validi o manca il campo
data
, la richiesta viene rifiutata con400 Bad Request
, con un codice di erroreINVALID_ARGUMENT
.Se il token di autenticazione fornito nella richiesta non è valido, la richiesta viene rifiutata con
401 Unauthorized
, con un codice di erroreUNAUTHENTICATED
.Se il token di registrazione FCM fornito nella richiesta non è valido, il comportamento non è definito. Il token non viene controllato ad ogni richiesta, tranne quando viene utilizzato per inviare una notifica push con FCM.
Se il trigger richiamabile viene richiamato, ma fallisce con un'eccezione non gestita o restituisce una promessa non riuscita, la richiesta viene rifiutata con
500 Internal Server Error
, con un codice di erroreINTERNAL
. Ciò impedisce che gli errori di codifica vengano accidentalmente esposti agli utenti finali.Se il callable viene richiamato e restituisce una condizione di errore esplicita utilizzando l'API fornita per le funzioni callable, la richiesta fallisce. Il codice di stato HTTP restituito si basa sulla mappatura ufficiale dello stato di errore sullo stato HTTP, come definito in code.proto . Il codice di errore specifico, il messaggio e i dettagli restituiti sono codificati nel corpo della risposta come descritto di seguito. Ciò significa che se la funzione restituisce un errore esplicito con stato
OK
, la risposta ha lo stato200 OK
, ma il campoerror
è impostato nella risposta.Se il trigger client ha esito positivo, lo stato della risposta è
200 OK
.
Formato della risposta: intestazioni
La risposta ha le seguenti intestazioni:
-
Content-Type: application/json
- Un facoltativo
; charset=utf-8
è consentito.
Corpo della risposta
La risposta da un endpoint client è sempre un oggetto JSON. Come minimo contiene result
o error
, insieme a eventuali campi facoltativi. Se la risposta non è un oggetto JSON o non contiene data
o error
, l'SDK del client dovrebbe considerare la richiesta come non riuscita con il codice di errore di Google INTERNAL (13)
.
-
error
- Se questo campo è presente, la richiesta viene considerata non riuscita, indipendentemente dal codice di stato HTTP o dalla presenza anchedata
. Il valore di questo campo deve essere un oggetto JSON nel formato standard di mappatura HTTP di Google Cloud per gli errori, con campi perstatus
,message
e (facoltativo)details
. Il campocode
non deve essere incluso. Se il campostatus
non è impostato o ha un valore non valido, il client deve considerare lo stato comeINTERNAL
, in conformità con code.proto . Sedetails
sono presenti, vengono inclusi in tutte le informazioni utente allegate all'errore nell'SDK del client, se applicabile.
Nota: il campodetails
qui è un valore fornito dall'utente. Non è necessariamente un elenco di valori codificati per tipo di prototipo come nel formato GoogleStatus
. -
result
- Il valore restituito dalla funzione. Può essere qualsiasi valore JSON valido. L'SDK delle funzioni Firebase codifica automaticamente il valore restituito dall'utente in questo formato JSON. Gli SDK client decodificano automaticamente questi parametri in tipi nativi in base al formato di serializzazione descritto di seguito.
Se sono presenti altri campi, devono essere ignorati.
Serializzazione
Il formato di serializzazione per i payload di dati arbitrari è lo stesso sia per la richiesta che per la risposta.
Per coerenza con la piattaforma, questi sono codificati in JSON come se fossero il valore di un campo Any
in un buffer del protocollo proto3, utilizzando la mappatura JSON standard . I valori di tipi semplici come null
, int
, double
o string
vengono codificati direttamente e non includono il relativo tipo esplicito. Quindi, float
e double
sono codificati allo stesso modo e potresti non sapere quale viene ricevuto dall'altro capo della chiamata. Per i tipi che non sono nativi di JSON, viene utilizzata la codifica proto3 tipizzata per il valore. Per ulteriori informazioni, consulta la documentazione per Qualsiasi codifica JSON .
Sono ammesse le seguenti tipologie:
- nullo -
null
- int (con segno o senza segno, fino a 32 bit) - ad esempio
3
o-30
. - float - ad esempio
3.14
- doppio - ad esempio
3.14
- booleano:
true
ofalse
- stringa - ad esempio
"hello world"
- carta geografica
- ad esempio {"x": 3}
- elenco
- ad esempio [1, 2, 3]
- lungo (con segno o senza segno, fino a 64 bit) - [vedi sotto per i dettagli]
I valori NaN
e Infinity
per float
e double
non sono supportati.
Tieni presente che long
è un tipo speciale normalmente non consentito in JSON, ma è coperto dalla specifica proto3. Ad esempio, questi sono codificati come:
lungo
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
non firmato lungo
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
In generale, la chiave @type
dovrebbe essere considerata riservata e non utilizzata per le mappe passate.
Poiché il tipo non è specificato per i tipi semplici, alcuni valori cambieranno tipo dopo il passaggio in rete. Un float
passato diventa un double
. Uno short
diventa un int
e così via. In Android, sia List
che JSONArray
sono supportati per i valori di elenco. In questi casi, il passaggio di un JSONArray produrrà un List
.
Se una mappa con un campo @type
sconosciuto viene deserializzata, viene lasciata come mappa. Ciò consente agli sviluppatori di aggiungere campi con nuovi tipi ai valori restituiti senza interrompere i client precedenti.
Esempi di codici
Gli esempi in questa sezione illustrano come codificare quanto segue:
- Un esempio callable.call in Swift
- Una risposta di successo per la chiamata
- Una risposta di errore per la chiamata
Esempio Callable.call in Swift per codificare
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
Intestazione della richiesta:
Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token
Corpo della richiesta:
{
"data": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": {
"@type": "type.googleapis.com/google.protobuf.Int64Value",
"value": "-123456789123456"
}
}
}
Risposta da codificare
return {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
};
Intestazione della risposta riuscita:
200 OK
Content-Type: application/json; charset=utf-8
Corpo della risposta riuscita:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Risposta fallita alla codifica
throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
"some-key": "some-value"
});
Intestazione della risposta non riuscita:
401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8
Corpo della risposta non riuscita:
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}