Specifiche del protocollo per https.onCall

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 del client per implementare l'API. Queste informazioni possono essere 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
    • È consentito un elemento ; charset=utf-8 facoltativo.
  • Facoltativo: Authorization: Bearer <token>
    • Un token ID utente Firebase Authentication per l'utente che ha eseguito l'accesso che effettua la richiesta. Il backend verifica automaticamente questo token e lo rende disponibile nel file context del gestore. Se il token non è valido, la richiesta viene rifiutata.
  • (Facoltativo) Firebase-Instance-ID-Token: <iid>
    • Il token di registrazione FCM dell'SDK del client Firebase. Deve essere una stringa. È disponibile nell'elemento context del gestore. È utilizzato per il targeting delle notifiche push.
  • Facoltativo: X-Firebase-AppCheck: <token>
    • Il token Firebase App Check fornito dall'app del cliente che effettua la richiesta. Il backend verifica automaticamente questo token e lo decodifica, inserisci appId nel valore context del gestore. Se il token non può essere verificata, la richiesta viene rifiutata. (disponibile per SDK >=3.14.0)

Se sono incluse altre intestazioni, la richiesta viene rifiutata, come descritto nella documentazione della risposta riportata di seguito.

Nota: nei client JavaScript, queste richieste attivano un preflight OPTIONS CORS, perché:

Il trigger richiamabile gestisce automaticamente queste richieste OPTIONS.

Corpo della richiesta

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. Questa viene decodificata 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 corretta e viene rifiutata.

Formato della risposta: codici di stato

Esistono diversi casi che potrebbero generare codici di stato HTTP diversi codici di stato delle stringhe per errors nella risposta.

  1. In caso di errore HTTP prima dell'attivazione dell'attivatore client, la risposta non viene gestita come funzione client. Ad esempio, se un client cerca di richiamare una funzione inesistente, riceve una risposta 404 Not Found.

  2. Se il trigger del client viene richiamato, ma la richiesta è nel formato errato, ad esempio non è JSON, presenta campi non validi o manca il campo data, la richiesta viene rifiutata con 400 Bad Request, con un codice di errore INVALID_ARGUMENT.

  3. Se il token di autenticazione fornito nella richiesta non è valido, la richiesta viene rifiutata con 401 Unauthorized e un codice di errore UNAUTHENTICATED.

  4. Se il token di registrazione FCM fornito nella richiesta non è valido, il comportamento non è definito. Il token non viene controllato per ogni richiesta, tranne quando viene utilizzato per inviare una notifica push con FCM.

  5. Se l'attivatore richiamabile viene invocato, ma non riesce con un'eccezione non gestita o restituisce una promessa non riuscita, la richiesta viene rifiutata con 500 Internal Server Error e un codice di errore INTERNAL. In questo modo, gli errori di codifica non vengono esposti accidentalmente agli utenti finali.

  6. Se la funzione richiamabile viene richiamata e restituisce una condizione di errore esplicita utilizzando l'API fornita per le funzioni richiamabili, la richiesta non va a buon fine. 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, il messaggio e i dettagli specifici restituiti sono codificati nel corpo della risposta come descritto di seguito. Ciò significa che se la funzione restituisce un errore esplicito con lo stato OK, la risposta avrà lo stato 200 OK, ma il campo error è impostato nella risposta.

  7. Se il trigger del client ha esito positivo, lo stato della risposta è 200 OK.

Formato della risposta: intestazioni

La risposta ha le seguenti intestazioni:

  • Content-Type: application/json
  • È consentito un elemento ; charset=utf-8 facoltativo.

Corpo della risposta

La risposta da un endpoint client è sempre un oggetto JSON. Come minimo contiene result o error, insieme ad eventuali campi facoltativi. Se la risposta non è un oggetto JSON o non contiene data o error, l'SDK del client deve considerare la richiesta come non riuscita con il codice di errore Google INTERNAL (13).

  • error: se questo campo è presente, la richiesta viene considerata non riuscita, indipendentemente dal codice di stato HTTP o dal fatto che sia presente anche data. Il valore di questo campo deve essere un oggetto JSON nel formato standard Google Cloud HTTP Mapping per gli errori, con i campi per status, message e (facoltativamente) details. Il campo code non deve essere incluso. Se il campo status non viene configurato o se è un valore non valido, il cliente deve considerare lo stato INTERNAL, in conformità con code.proto. Se è presente details, viene incluso in tutte le informazioni utente allegate all'errore nell'SDK del client, se applicabile.
    Nota: il campo details qui è un valore fornito dall'utente. Non si tratta necessariamente di un elenco di valori associati al tipo di protocollo, come nel formato Status di Google.
  • result: il valore restituito dalla funzione. Può essere qualsiasi valore JSON valido. L'SDK firebase-functions codifica automaticamente il valore restituito dall'utente in questo formato JSON. Gli SDK del 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 garantire la coerenza della piattaforma, questi vengono codificati in JSON come se fossero il valore di un campo Any in un buffer di protocollo proto3, usando il mappamento JSON standard. I valori di tipi semplici come null, int, double o string vengono codificati direttamente e non includono il tipo esplicito. Pertanto, float e double sono codificati allo stesso modo e potresti non sapere quale viene ricevuto all'altro capo della chiamata. Per i tipi non nativi di JSON, viene utilizzata la codifica proto3 digitata per il valore. Per ulteriori informazioni, consulta la documentazione relativa alla codifica con qualsiasi formato JSON.

Sono consentiti i seguenti tipi:

  • null - null
  • int (firmato o non firmato, fino a 32 bit), ad esempio 3 o -30.
  • numero in virgola mobile: ad es. 3.14
  • Doppio: ad es. 3.14
  • booleano - true o false
  • stringa: ad es. "hello world"
  • mappa<string, any=""> ad es. {"x": 3}</string,>
  • elenco : ad es. [1, 2, 3]
  • lunga (con o senza firma, 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 non normalmente consentito in JSON, ma è coperto dalla specifica proto3. Ad esempio, vengono codificati come:

Lungo

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

unsigned long

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

In generale, la chiave @type deve essere considerata riservata e non deve essere utilizzata per le mappe trasmesse.

Poiché il tipo non viene specificato per i tipi semplici, alcuni valori cambieranno dopo il trasferimento. Un float trasmesso diventa double. Un short diventa int e così via. In Android, per i valori dell'elenco sono supportati sia List sia JSONArray. 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. In questo modo gli sviluppatori possono aggiungere campi con nuovi tipi ai valori restituiti senza danneggiare i client precedenti.

Esempi di codice

Gli esempi in questa sezione illustrano come codificare quanto segue:

  • Un esempio di chiamata di callable.call in Swift
  • Una risposta positiva per la chiamata
  • Una risposta di errore per la chiamata

Esempio di Callable.call in Swift per la codifica

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 per la codifica

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

Intestazione 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 di errore di codifica

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

Intestazione 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"
        }
    }
}