Una chiave API è una stringa univoca utilizzata per indirizzare le richieste al tuo progetto Firebase quando interagisci con i servizi Firebase e Google. Questa pagina descrive informazioni di base sulle chiavi API, nonché le best practice per l'utilizzo e la gestione delle chiavi API con le app Firebase.
Informazioni generali sulle chiavi API e su Firebase
Le chiavi API per Firebase sono diverse dalle chiavi API tipiche
A differenza di come vengono in genere utilizzate, le chiavi API per i servizi Firebase non vengono utilizzate per controllare l'accesso alle risorse di backend; questa operazione può essere eseguita solo con Firebase Security Rules (per controllare quali utenti finali possono accedere alle risorse) e Firebase App Check (per controllare quali app possono accedere alle risorse).
In genere, devi proteggere scrupolosamente le chiavi API (ad esempio, utilizzando un servizio di vault o impostando le chiavi come variabili di ambiente); tuttavia, le chiavi API per i servizi Firebase possono essere incluse nel codice o nei file di configurazione archiviati.
Sebbene le chiavi API per i servizi Firebase siano sicure da includere nel codice, devi esaminarle e applicare restrizioni e limiti appropriati.
Creazione di chiavi API
Un progetto Firebase può avere molte chiavi API, ma ogni chiave API può essere associata a un solo progetto Firebase.
Firebase crea automaticamente le chiavi API per il tuo progetto quando esegui una delle seguenti operazioni:
- Crea un progetto Firebase >
Browser key
creato automaticamente - Crea un'app Apple Firebase >
iOS key
creazione automatica - Crea un'app Firebase per Android >
Android key
creazione automatica
Puoi anche creare le tue chiavi API nella console Google Cloud, ad esempio per lo sviluppo o il debug. Scopri di più su quando questo potrebbe essere consigliato più avanti in questa pagina.
Trovare le chiavi API
Puoi visualizzare e gestire tutte le chiavi API del tuo progetto nel riquadro API e servizi > Credenziali nella console Google Cloud.
Puoi anche trovare la chiave API che viene abbinata automaticamente a un'app Firebase nei seguenti luoghi. Per impostazione predefinita, tutte le app Firebase del progetto per la stessa piattaforma (Apple, Android o web) utilizzeranno la stessa chiave API.
App Apple Firebase: trova la chiave API abbinata automaticamente nel file di configurazione Firebase,
, nel campoGoogleService-Info.plist API_KEY
.App Firebase per Android: trova la chiave API abbinata automaticamente nel file di configurazione di Firebase,
, nel campogoogle-services.json current_key
.App web Firebase: trova la chiave API abbinata automaticamente nell'oggetto di configurazione Firebase, nel campo
apiKey
.
Utilizzo di una chiave API
Le chiavi API per Firebase vengono utilizzate per identificare il tuo progetto Firebase quando interagisci con Firebase o i servizi Google. In particolare, vengono utilizzate per associare le richieste API al tuo progetto per la quota e la fatturazione. Sono utili anche per accedere ai dati pubblici.
Per la stragrande maggioranza degli sviluppatori e dei casi d'uso, non interagisci direttamente con queste chiavi API. Quando la tua app chiama un'API Firebase che richiede una chiave API fornita dal client web o mobile, la tua app cercherà automaticamente una chiave API nella configurazione Firebase. Questa configurazione è stata aggiunta al codebase della tua app quando l'hai collegata a Firebase.
Tieni presente che puoi fornire la chiave API della tua app all'interno dell'app utilizzando un meccanismo diverso, ad esempio le opzioni Firebase o le variabili di ambiente.
Inoltre, per alcune API REST per i servizi Firebase, potrebbe essere necessario passare esplicitamente il valore della chiave API alla chiamata come parametro di query. Questo esempio mostra come effettuare una richiesta utilizzando l'API Firebase Authentication:
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=API_KEY
Esamina e applica le limitazioni appropriate alle chiavi API (consigliato)
Sebbene non sia necessario trattare una chiave API per i servizi Firebase come un segreto, devi esaminare e applicare restrizioni e limiti come descritto in questa sezione.
Esaminare le API aggiunte automaticamente alla lista consentita per le chiavi API Firebase
Quando Firebase crea una chiave API nel tuo progetto, aggiungiamo automaticamente "Limitazioni API" a questa chiave. Le API aggiunte a questa lista consentita sono API correlate a Firebase che richiedono al client di fornire una chiave API insieme alla chiamata. Tieni presente che la maggior parte delle API necessarie per l'utilizzo dei servizi Firebase non deve essere inclusa nella lista consentita per le chiavi API.
Poiché Firebase aggiunge le API necessarie per tutti i servizi Firebase, la lista consentita per una chiave API può includere API per prodotti che non utilizzi. Puoi rimuovere le API dalla lista consentita, ma devi fare molta attenzione a non rimuovere le API richieste per Firebase e i servizi Firebase che utilizzi (consulta l'elenco delle API correlate a Firebase che devono essere incluse nella lista consentita per ogni servizio / prodotto). In caso contrario, si verificheranno errori durante le chiamate ai servizi Firebase.
Riduci la quota se utilizzi Authentication basati su password
Se utilizzi Firebase Authentication basato su password e qualcuno entra in possesso della tua chiave API, non potrà accedere a nessuno dei database del tuo progetto Firebase o ai dati Cloud Storage purché questi dati siano protetti da Firebase Security Rules. Tuttavia, potrebbero utilizzare la tua chiave API per accedere agli endpoint di autenticazione di Firebase ed effettuare richieste di autenticazione per il tuo progetto.
Per ridurre la possibilità che qualcuno possa utilizzare in modo improprio una chiave API per
tentare un attacco di forza bruta, puoi ridurre la quota predefinita degli
endpoint identitytoolkit.googleapis.com
in modo che riflettano le normali aspettative di traffico
della tua app. Tieni presente che se riduci questa quota e la tua app
acquisisce improvvisamente utenti, potresti riscontrare errori di accesso finché non aumenti la quota.
Puoi modificare le quote API del progetto nella
console Google Cloud.
Utilizza chiavi API separate e limitate per qualsiasi servizio non Firebase
Sebbene le chiavi API utilizzate per i servizi Firebase non debbano in genere essere trattate come segrete, devi adottare alcune precauzioni aggiuntive con le chiavi API che utilizzi con altre API Google Cloud.
Se utilizzi un'API Google Cloud (su qualsiasi piattaforma) che non è per un servizio / prodotto Firebase, ti consigliamo vivamente di creare chiavi API separate e limitate da utilizzare con queste API. Ciò è particolarmente importante se l'API è per un servizio Google Cloud fatturabile.
Ad esempio, se utilizzi Firebase ML e le API Cloud Vision su iOS, devi creare chiavi API separate da utilizzare solo per accedere alle API Cloud Vision.
Utilizzando chiavi API separate e limitate per le API non Firebase, puoi ruotare o sostituire le chiavi quando necessario e aggiungere ulteriori limitazioni alle chiavi API senza interrompere l'utilizzo dei servizi Firebase.
Visualizza le istruzioni per creare chiavi specifiche per l'API
Queste istruzioni descrivono come creare una chiave API separata e con limitazioni per un'API
fittizia chiamata Super Service API
.
Passaggio 1: configura le chiavi API esistenti per impedire l'accesso a Super Service API
Apri la pagina Credenziali della console Google Cloud. Quando richiesto, seleziona il progetto.
Per ogni chiave API esistente nell'elenco, apri la visualizzazione di modifica.
Nella sezione Restrizioni delle API, seleziona Limita chiave, quindi aggiungi all'elenco tutte le API a cui vuoi che la chiave API abbia accesso. Assicurati di non includere l'API per cui stai creando una chiave API separata (in questo esempio,
Super Service API
).Quando configuri le restrizioni delle API di una chiave API, dichiari esplicitamente le API a cui la chiave ha accesso. Per impostazione predefinita, quando nella sezione Restrizioni delle API è selezionata l'opzione Non limitare chiave, una chiave API può essere utilizzata per accedere a qualsiasi API abilitata per il progetto.
Ora, le tue chiavi API esistenti non concederanno l'accesso a Super Service API
, ma
ogni chiave continuerà a funzionare per le API che hai aggiunto al suo elenco di
limitazioni API.
Passaggio 2: crea e utilizza una nuova chiave API per l'accesso a Super Service API
Torna alla pagina Credenziali. Assicurati che il progetto Firebase sia ancora selezionato.
Fai clic su Crea credenziali > Chiave API. Prendi nota della nuova chiave API, poi fai clic su Limita chiave.
Nella sezione Restrizioni delle API, seleziona Limita chiave, quindi aggiungi all'elenco solo
Super Service API
.Questa nuova chiave API concede l'accesso solo a
Super Service API
.Configura l'app e i servizi in modo che utilizzino la nuova chiave API.
Utilizza chiavi API specifiche per l'ambiente (consigliato)
Se configuri progetti Firebase diversi per ambienti diversi, ad esempio staging e produzione, è importante che ogni istanza dell'app interagisca con il progetto Firebase corrispondente. Ad esempio, l'istanza dell'app di staging non deve mai comunicare con il progetto Firebase di produzione. Ciò significa anche che l'app di staging deve utilizzare le chiavi API associate al progetto Firebase di staging.
Per ridurre i problemi di promozione delle modifiche al codice dallo sviluppo allo staging alla produzione, anziché includere le chiavi API nel codice stesso, impostale come variabili di ambiente o includile in un file di configurazione.
Tieni presente che se utilizzi Firebase Local Emulator Suite per lo sviluppo insieme a Firebase ML, devi creare e utilizzare una chiave API solo per il debug. Le istruzioni per creare questo tipo di chiave sono disponibili nella documentazione di Firebase ML.
Domande frequenti e risoluzione dei problemi
Domande frequenti
Le chiavi API per i servizi Firebase sono limitate per impostazione predefinita?
Sì, per impostazione predefinita, tutte le chiavi API di cui Firebase esegue il provisioning automatico per l'utilizzo con le API correlate a Firebase hanno le "Limitazioni API" applicate automaticamente. Consulta l'elenco delle API correlate a Firebase che si trovano in questa lista consentita.
Le API aggiunte a questa lista consentita sono quelle chiamate dai servizi Firebase dal codice client e richiedono chiavi API per l'identificazione del tuo progetto o della tua app Firebase. Tieni presente che la maggior parte delle API necessarie per l'utilizzo dei servizi Firebase non deve essere inclusa nella lista consentita per le tue chiavi API.
Poiché Firebase aggiunge le API necessarie per tutti i servizi Firebase, la lista consentita per una chiave API può includere API per prodotti che non utilizzi. Puoi rimuovere le API dalla lista consentita, ma devi fare molta attenzione a non rimuovere le API richieste per Firebase e i servizi Firebase che utilizzi (consulta l'elenco delle API correlate a Firebase che devono essere incluse nella lista consentita per ogni servizio / prodotto). In caso contrario, si verificheranno errori durante le chiamate ai servizi Firebase.
Puoi visualizzare tutte le tue chiavi API e le relative "limitazioni API" nel riquadro API e servizi > Credenziali della console Google Cloud.
Tieni presente quanto segue su come Firebase applica queste "limitazioni API":
A partire da maggio 2024, tutte le chiavi API nuove di cui è stato eseguito il provisioning automatico da Firebase sono automaticamente limitate all'elenco delle API correlate a Firebase.
A maggio 2024, tutte le chiavi API esistenti e senza restrizioni di cui Firebase aveva precedentemente eseguito il provisioning automatico sono limitate all'elenco delle API correlate a Firebase più qualsiasi API attualmente abilitata del progetto.
Le chiavi API esistenti e già limitate di cui Firebase aveva eseguito il provisioning automatico in precedenza non sono state modificate.
Le chiavi API esistenti di cui non è stato eseguito il provisioning automatico da Firebase non sono state modificate.
Come posso determinare quale chiave API è associata alla mia app Firebase?
Puoi utilizzare una delle seguenti opzioni per determinare quale chiave API è associata alla tua app Firebase:
Vai a Impostazioni progetto, quindi scorri verso il basso fino alla scheda Le tue app.
Seleziona l'app che ti interessa.
Ottieni il file/oggetto di configurazione Firebase per l'app di interesse, quindi trova la relativa chiave API:
Apple: scarica il
GoogleService-Info.plist
e poi trova il campoAPI_KEY
.Android: scarica
google-services.json
, trova la configurazione per l'app di interesse (cerca il nome del pacchetto) e poi trova il campocurrent_key
Web: seleziona l'opzione Config, quindi individua il campo
apiKey
.
Ottieni il file/oggetto di configurazione Firebase per l'app di interesse eseguendo il seguente comando:
firebase apps:sdkconfig
PLATFORM FIREBASE_APP_ID - PLATFORM (uno dei seguenti):
IOS
|ANDROID
|WEB
- FIREBASE_APP_ID: l'identificatore univoco assegnato da Firebase per la tua app Firebase (trova l'ID app)
- PLATFORM (uno dei seguenti):
Nella configurazione Firebase stampata dell'app, trova la chiave API:
Apple: trova il campo
API_KEY
Android: trova la configurazione per l'app di interesse (cerca il nome del pacchetto) e poi trova il campo
current_key
.Web: trova il campo
apiKey
Ottieni
apiKeyId
(l'UID) della chiave API chiamando l'endpoint applicabile per l'app di interesse, quindi passa il valoreapiKeyId
al passaggio successivo.- Apple: chiama il numero
projects.iosApps.get
- Android: chiama il numero
projects.androidApps.get
- Web: chiama il numero
projects.webApps.get
- Apple: chiama il numero
Ottieni la stringa della chiave API chiamando
projects.locations.keys.getKeyString
.Questo
keyString
è lo stesso valore che si trova nell'artefatto di configurazione dell'app (Apple | Android | web).
Posso avere due chiavi API elencate per la stessa app Firebase nel mio file/oggetto di configurazione Firebase?
App Apple Firebase: ogni app ha il proprio file di configurazione e può avere solo una chiave API elencata.
App Android Firebase: tutte le app Android nel progetto Firebase sono elencate nello stesso file di configurazione e ogni app può avere una sola chiave API elencata. Tuttavia, ogni app in questo file di configurazione può avere una chiave diversa elencata.
App web Firebase: ogni app ha il proprio oggetto di configurazione e può avere un'unica chiave API elencata.
Tuttavia, puoi utilizzare più chiavi API con un'unica app. Devi fornire un meccanismo per consentire alla tua app di accedere a queste altre chiavi API, ad esempio tramite una variabile di ambiente. Il meccanismo per accedere alle altre chiavi API non può dipendere dal fatto che queste chiavi API siano elencate nel file/oggetto di configurazione di Firebase.
In che modo Firebase sa a quale chiave API associare un'app (ad esempio nel file/oggetto di configurazione di Firebase)?
Quando ottieni per la prima volta il file/oggetto di configurazione Firebase della tua app, Firebase verifica se nel tuo progetto sono presenti chiavi API esistenti con "Limitazioni dell'applicazione" che corrispondono all'app (ad esempio, un ID bundle corrispondente per l'app Apple).
Se Firebase non trova chiavi con limitazioni corrispondenti, elenca nel file/oggetto di configurazione iOS key
per le app Apple, Android key
per le app Android e Browser key
per le app web (supponendo che queste chiavi esistano e non abbiano "Limitazioni dell'applicazione" che impediscano loro di corrispondere a quell'app).
Posso eliminare manualmente la chiave API e il campo dal mio file/oggetto di configurazione di Firebase?
Sì, puoi eliminare manualmente la chiave API dal file/oggetto di configurazione. Tuttavia, devi fornire un altro meccanismo per consentire alla tua app di accedere a una chiave API (ad esempio tramite una variabile di ambiente). In caso contrario, tutte le chiamate ai servizi Firebase non andranno a buon fine.
Posso modificare manualmente il mio file/oggetto di configurazione Firebase con chiavi API diverse?
Sì, puoi modificare manualmente un file/oggetto di configurazione per associare una chiave API diversa a un'app.
Tieni presente che se recuperi il file/oggetto di configurazione della tua app dalla console, verranno sempre elencate le chiavi API che Firebase associa automaticamente a quell'app. Pertanto, dovrai ripetere le modifiche manuali, se necessario.
Posso spostare una chiave API da un progetto Firebase a un altro?
No, una chiave API identifica solo un progetto specifico e non può essere spostata in un altro progetto.
Cosa succede se elimino una chiave API elencata nella console Google Cloud?
Se elimini una chiave API in uso da un'app, le chiamate API da quell'app non andranno a buon fine. Potresti ricevere report, email o errori che indicano che stai tentando di utilizzare una chiave API non valida.
L'eliminazione di una chiave API è definitiva e non può essere annullata.
Quali API sono richieste nella lista consentita "Restrizioni API" per una chiave API di Firebase?
Per una chiave API di Firebase, le uniche API che devono essere presenti nella lista consentita "Limitazioni API" della chiave sono quelle che richiedono al client di fornire una chiave API insieme alla chiamata. Tieni presente che pochissime API correlate a Firebase hanno questo requisito. La maggior parte delle API correlate a Firebase attivate nel tuo progetto non deve essere nella lista consentita "Limitazioni API" della chiave.
Utilizza la seguente tabella per determinare quali API correlate a Firebase devono essere incluse nella lista consentita "Restrizioni API" per una chiave API Firebase. Ricorda che le chiavi API di Firebase devono essere utilizzate solo per i servizi Firebase. Scopri di più sulla creazione di chiavi API separate e con limitazioni per tipi specifici di API.
Puoi visualizzare e gestire le chiavi API del tuo progetto nel riquadro API e servizi > Credenziali nella console Google Cloud.
Nome API (nome servizio) | Nome visualizzato dell'API | Servizio / prodotto Firebase associato |
---|---|---|
firebase.googleapis.com | API Firebase Management | tutti i prodotti |
logging.googleapis.com | API Cloud Logging | tutti i prodotti |
firebaseinstallations.googleapis.com | API Firebase Installations | Cloud Messaging, Crashlytics, In-App Messaging, Performance Monitoring, Remote Config, Firebase ML |
firebaseappcheck.googleapis.com | API Firebase App Check | App Check |
firebaseappdistribution.googleapis.com | API Firebase App Distribution | App Distribution |
firebaseapptesters.googleapis.com | API Firebase App Testers | App Distribution |
identitytoolkit.googleapis.com | API Identity Toolkit | Authentication |
securetoken.googleapis.com | API Token Service | Authentication |
firebaserules.googleapis.com * | API Firebase Rules | Cloud Firestore, Cloud Storage, Realtime Database |
datastore.googleapis.com | API Cloud Datastore | Cloud Firestore |
firestore.googleapis.com | API Google Cloud Firestore | Cloud Firestore |
fcmregistrations.googleapis.com | API FCM Registration | Cloud Messaging |
firebasestorage.googleapis.com | API Cloud Storage for Firebase | Cloud Storage |
firebasedynamiclinks.googleapis.com | API Firebase Dynamic Links | Dynamic Links |
firebasehosting.googleapis.com * | API Firebase Hosting | Hosting |
firebaseinappmessaging.googleapis.com | API Firebase In-App Messaging | In-App Messaging |
firebaseml.googleapis.com | API Firebase ML | Firebase ML |
mlkit.googleapis.com ** | API ML Kit | Firebase ML |
mobilecrashreporting.googleapis.com | Mobile Crash Reporting API | Performance Monitoring |
play.googleapis.com | API Google Play Android Developer | Performance Monitoring |
firebaseremoteconfig.googleapis.com | API Firebase Remote Config | Performance Monitoring, Remote Config |
firebaseremoteconfigrealtime.googleapis.com | API Firebase Remote Config in tempo reale | Performance Monitoring, Remote Config |
cloudconfig.googleapis.com ** | N/D | Remote Config |
firebasedatabase.googleapis.com * | API Firebase Realtime Database | Realtime Database |
firebasevertexai.googleapis.com | API Firebase AI Logic | SDK client Firebase AI Logic |
* Obbligatorio solo se utilizzi la chiave API di Firebase con strumenti di terze parti o l'accesso REST diretto al servizio / prodotto Firebase.
** Obbligatorio per le versioni precedenti dell'SDK del prodotto. Se utilizzi l'ultima versione dell'SDK, l'API non deve essere inclusa nella lista consentita della chiave.
Risoluzione dei problemi
Come faccio a
correggere un errore API_KEY_SERVICE_BLOCKED
o Forbidden 403 che indica
che le richieste a questa API sono bloccate?
Segui le indicazioni riportate in queste domande frequenti se ricevi un errore API_KEY_SERVICE_BLOCKED
o un errore simile al seguente:
Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.
La chiave API utilizzata dalla tua app per chiamare l'API probabilmente ha "Limitazioni API" applicate e la lista consentita della chiave non include l'API.
Se ricevi questo errore quando provi a utilizzare un servizio / prodotto correlato a Firebase, assicurati che la chiave API che stai utilizzando includa tutte le API richieste nell'elenco consentito "Limitazioni API" della chiave.
Se ricevi questo errore quando tenti di utilizzare un servizio non Firebase, ti consigliamo vivamente di creare una nuova chiave API specifica per quel servizio e per l'API. Le chiavi API Firebase devono essere utilizzate solo per i servizi / prodotti Firebase. Scopri di più sulla creazione di chiavi API separate e con limitazioni per tipi specifici di API.
Come faccio a risolvere questo errore? "Impossibile recuperare l'ID misurazione di questa app Firebase dal server."
La chiave API utilizzata dalla tua app web probabilmente ha "Limitazioni API" applicate. In questo caso, assicurati che l'API Firebase Management sia presente nell'elenco delle API consentite.
Ho ricevuto un'email o un errore che indica che la mia chiave API non è valida. Cosa è successo e come posso risolvere il problema?
Di seguito sono riportate alcune delle cause più comuni di chiavi API non valide:
La chiave API ha "Limitazioni chiave API" applicate che la rendono non corrispondente all'app che tenta di utilizzare la chiave ("Limitazioni delle applicazioni") o inutilizzabile per l'API chiamata ("Limitazioni API").
La chiave API è stata eliminata dal progetto nella console Google Cloud.
La chiave API non è stata creata per l'ID progetto elencato nel file/oggetto di configurazione Firebase dell'app.
Un modo per risolvere il problema è ottenere la versione aggiornata del file/oggetto di configurazione Firebase della tua app, quindi sostituire il vecchio file/oggetto di configurazione con il nuovo file/oggetto aggiornato. Prima di inviare un file di configurazione per il download o di visualizzare un oggetto di configurazione nella console, Firebase verifica che le chiavi API elencate corrispondano alle app.