Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Specifiche del protocollo per https.onCall

Un trigger https.onCall per le funzioni cloud è 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 gli SDK Android, iOS o Web.

Formato della richiesta: intestazioni

La richiesta HTTP a un endpoint di trigger richiamabile deve essere un POST con le seguenti intestazioni:

  • Richiesto: Content-Type: application/json
    • Un opzionale ; charset=utf-8 è consentito.
  • Opzionale: Authorization: Bearer <token>
    • Un token ID utente di autenticazione Firebase per l'utente che ha effettuato l'accesso che ha effettuato 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.
  • Opzionale: Firebase-Instance-ID-Token: <iid>
    • Token ID istanza dall'SDK del client Firebase. Questa deve essere una stringa. Questo è disponibile nel context del gestore. È particolarmente utile per l'invio di notifiche push.

Se vengono incluse altre intestazioni, la richiesta viene respinta, come descritto nella documentazione di risposta di seguito.

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

  • application/json non è permesso. Deve essere text/plain o application/x-www-form-urlencoded .
  • L'intestazione di Authorization non è un'intestazione di richiesta con elenco di sicurezza CORS .
  • Allo stesso modo non sono consentite altre intestazioni.

Il trigger richiamabile gestisce automaticamente queste richieste OPTIONS .

Corpo della richiesta

Il corpo della richiesta HTTP dovrebbe essere un oggetto JSON con uno dei seguenti campi:

  • Richiesto: data - L'argomento passato alla funzione. Questo può essere qualsiasi valore JSON valido. Questo viene automaticamente decodificato in tipi JavaScript nativi in ​​base al formato di serializzazione descritto di seguito.

Se nella richiesta sono presenti altri campi, il back-end considera la richiesta non valida e viene respinta.

Formato di risposta: codici di stato

Esistono diversi casi che possono comportare codici di stato HTTP diversi e codici di stato della stringa per errori nella risposta.

  1. Nel caso di un errore HTTP prima che venga richiamato il trigger client , la risposta non viene gestita come funzione client. Ad esempio, se un client tenta di richiamare una funzione inesistente, riceve una risposta 404 Not Found .

  2. Se viene richiamato il trigger client, ma la richiesta è nel formato errato, come non essere JSON, avere campi non validi o perdere 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 , con un codice di errore di UNAUTHENTICATED .

  4. Se il token ID istanza fornito nella richiesta non è valido, il comportamento non è definito. Il token ID istanza non viene verificato su ogni richiesta, tranne quando viene utilizzato per inviare una notifica push con FCM.

  5. Se viene richiamato il trigger richiamabile, 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 errore INTERNAL . Ciò impedisce che gli errori di codifica vengano esposti accidentalmente agli utenti finali.

  6. Se viene richiamato il callable e restituisce una condizione di errore esplicito utilizzando l'API fornita per le funzioni callable, la richiesta non riesce. 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 stato 200 OK , ma il campo di error viene impostato nella risposta.

  7. Se l'attivazione del client ha esito positivo, lo stato della risposta è 200 OK .

Formato di risposta: intestazioni

La risposta ha le seguenti intestazioni:

  • Content-Type: application/json
  • Un optional ; charset=utf-8 è consentito.

Corpo di risposta

La risposta da un endpoint client è sempre un oggetto JSON. Come minimo contiene data o error , insieme a tutti i campi opzionali. Se la risposta non è un oggetto JSON o non contiene data o error , l'SDK client deve considerare la richiesta 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 dalla presenza di data . Il valore di questo campo dovrebbe essere un oggetto JSON nel formato standard di Mappatura HTTP di Google Cloud per gli errori, con campi per status , message e (facoltativamente) details . Il campo del code non deve essere incluso. Se il campo dello status non è impostato o è un valore non valido, il client deve considerare lo stato come INTERNAL , in conformità con code.proto . Se i details sono presenti, sono inclusi nelle informazioni utente allegate all'errore nell'SDK client, se applicabile.
    Nota: il campo details qui è un valore fornito dall'utente. Non è necessariamente un elenco di valori codificati per tipo di proto come nel formato dello Status Google.
  • data - Il valore restituito dalla funzione. Questo 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 payload di dati arbitrari è lo stesso sia per la richiesta che per la risposta.

Per coerenza della piattaforma, questi sono codificati in JSON come se fossero il valore di un campo Any in un buffer di protocollo proto3, utilizzando la mappatura JSON standard . I valori di tipi semplici come null , int , double o string sono codificati direttamente e non includono il loro tipo esplicito. Quindi, un float e un double vengono codificati allo stesso modo e potresti non sapere quale viene ricevuto dall'altra parte della chiamata. Per i tipi che non sono nativi di JSON, viene utilizzata la codifica proto3 tipizzata per il valore. Per ulteriori informazioni, consultare la documentazione per qualsiasi codifica JSON .

Sono consentiti i seguenti tipi:

  • null - null
  • int (con o senza segno, fino a 32 bit) - ad es. 3 o -30 .
  • galleggiante - ad es. 3.14
  • doppio - ad es. 3.14
  • booleano: true o false
  • stringa - ad es. "hello world"
  • carta geografica - ad es. {"x": 3}
  • elenco - ad es. [1, 2, 3]
  • lungo (con o senza segno, fino a 64 bit) - [vedi sotto per i dettagli]

NaN valori NaN e Infinity per float e double non sono supportati.

Si noti 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 a lungo

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

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

Poiché il tipo non è specificato per tipi semplici, alcuni valori cambieranno tipo dopo aver passato il filo. Un float passato diventa un double . Un short diventa un int e così via. In Android, sia List che JSONArray sono supportati per i valori dell'elenco. In questi casi, passare un JSONArray produrrà un List .

Se una mappa con un campo @type sconosciuto viene deserializzata, viene lasciata come una mappa. Ciò consente agli sviluppatori di aggiungere campi con nuovi tipi ai loro valori di ritorno senza rompere i client più vecchi.

Esempi di codice

Gli esempi in questa sezione illustrano come codificare quanto segue:

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

Callable.call esempio in Swift da codificare

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

Intestazione richiesta:

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

Ente richiesta:

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

Risposta alla codifica

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

Intestazione risposta riuscita:

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

Ente di risposta riuscito:

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

Risposta errata alla 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"
        }
    }
}