Questo documento spiega come implementare l'autorizzazione OAuth 2.0 per accedere all'API YouTube Data tramite applicazioni in esecuzione su dispositivi come TV, console per videogiochi e stampanti. In particolare, questo flusso è progettato per i dispositivi che non hanno accesso a un browser o che hanno funzionalità di input limitate.
OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo privati i nomi utente, le password e altre informazioni. Ad esempio, un'applicazione TV potrebbe utilizzare OAuth 2.0 per ottenere l'autorizzazione per selezionare un file archiviato su Google Drive.
Poiché le applicazioni che utilizzano questo flusso sono distribuite ai singoli dispositivi, si presume che le app non possano mantenere secret. Possono accedere alle API di Google mentre l'utente è presente nell'app o quando l'app è in esecuzione in background.
Alternative
Se stai scrivendo un'app per una piattaforma come Android, iOS, macOS, Linux o Windows (inclusa la piattaforma Universal Windows) che ha accesso al browser e a funzionalità di input complete, utilizza il flusso OAuth 2.0 per applicazioni mobile e desktop. Dovresti usare questo flusso anche se la tua app è uno strumento a riga di comando senza un'interfaccia grafica.
Se vuoi accedere solo agli utenti con i loro Account Google e utilizzare il token ID JWT per ottenere le informazioni di base del profilo dell'utente, consulta la sezione Accesso su TV e dispositivi di input con limitazioni.
Prerequisiti
Abilita le API per il progetto
Qualsiasi applicazione che chiama le API di Google deve abilitare queste API in API Console.
Per abilitare un'API per il tuo progetto:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- Utilizza la pagina Raccolta per individuare e attivare l'API di dati di YouTube. Trova e abilita anche le altre API utilizzate dalla tua applicazione.
Crea credenziali di autorizzazione
Qualsiasi applicazione che utilizza OAuth 2.0 per accedere alle API di Google deve avere credenziali di autorizzazione che identificano l'applicazione sul server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il tuo progetto. Le applicazioni possono quindi utilizzare le credenziali per accedere alle API abilitate per il progetto.
- Go to the Credentials page.
- Fai clic su Crea credenziali > ID client OAuth.
- Seleziona il tipo di applicazione TV e dispositivi di input con limitazioni.
- Assegna un nome al client OAuth 2.0 e fai clic su Crea.
Identifica gli ambiti di accesso
Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare il livello di accesso che concedono all'applicazione. Pertanto, potrebbe esistere una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso degli utenti.
Prima di iniziare a implementare l'autorizzazione OAuth 2.0, ti consigliamo di identificare gli ambiti a cui la tua app dovrà disporre dell'autorizzazione per accedere.
La YouTube Data API v3 utilizza i seguenti ambiti:
| Mirini con ingrandimento | |
|---|---|
| https://www.googleapis.com/auth/youtube | Gestisci il tuo account YouTube |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Visualizzare un elenco dei tuoi attuali membri attivi del canale, il loro livello corrente e quando sono diventati membri |
| https://www.googleapis.com/auth/youtube.force-ssl | Visualizzare, modificare ed eliminare definitivamente video, valutazioni, commenti e sottotitoli di YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Visualizza il tuo account YouTube |
| https://www.googleapis.com/auth/youtube.upload | Gestisci i tuoi video su YouTube |
| https://www.googleapis.com/auth/youtubepartner | Visualizzare e gestire le risorse e i relativi contenuti su YouTube |
| https://www.googleapis.com/auth/youtubepartner-channel-audit | Visualizzare le informazioni private del tuo canale YouTube pertinenti durante la procedura di revisione con un partner di YouTube |
Consulta l'elenco Ambiti consentiti per le app o i dispositivi installati.
Ottenere i token di accesso OAuth 2.0
Anche se l'applicazione viene eseguita su un dispositivo con capacità di input limitate, per completare questo flusso di autorizzazione gli utenti devono avere accesso separato a un dispositivo con funzionalità di input più avanzate. Il flusso prevede i seguenti passaggi:
- L'applicazione invia al server di autorizzazione di Google una richiesta che identifica gli ambiti a cui l'applicazione richiederà l'autorizzazione ad accedere.
- Il server risponde con diverse informazioni utilizzate nei passaggi successivi, ad esempio un codice dispositivo e un codice utente.
- Puoi mostrare le informazioni che l'utente può inserire su un dispositivo separato per autorizzare la tua app.
- L'applicazione avvia il polling del server di autorizzazione di Google per determinare se l'utente ha autorizzato la tua app.
- L'utente passa a un dispositivo con funzionalità di input più avanzate, avvia un browser web, accede all'URL visualizzato al passaggio 3 e inserisce un codice che viene visualizzato anche al passaggio 3. L'utente potrà quindi concedere (o negare) l'accesso alla tua applicazione.
- La risposta successiva alla richiesta di polling contiene i token necessari all'app per autorizzare le richieste per conto dell'utente. (Se l'utente ha rifiutato l'accesso alla tua applicazione, la risposta non contiene token.)
L'immagine seguente illustra questa procedura:
Questi passaggi vengono descritti in dettaglio nelle sezioni seguenti. Data la gamma di funzionalità e gli ambienti di runtime dei dispositivi, gli esempi mostrati in questo documento utilizzano l'utilità a riga di comando curl. Questi esempi devono essere facili da trasferire in vari linguaggi e runtime.
Passaggio 1: richiedi i codici utente e del dispositivo
In questo passaggio, il dispositivo invia una richiesta POST HTTP al server di autorizzazione di Google, all'indirizzo https://oauth2.googleapis.com/device/code, che identifica l'applicazione e gli ambiti di accesso a cui l'applicazione vuole accedere per conto dell'utente.
Devi recuperare questo URL dal
documento di rilevamento utilizzando il
valore dei metadati device_authorization_endpoint. Includi i seguenti parametri della richiesta HTTP:
| Parametri | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obbligatorio
L'ID client dell'applicazione. Puoi trovare questo valore nella sezione API Console Credentials page. |
||||||||||||||||
scope |
Obbligatorio
Un elenco di ambiti delimitato da spazi che identificano le risorse a cui l'applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di consenso che Google mostra all'utente. Consulta l'elenco Ambiti consentiti per le app o i dispositivi installati. Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare il livello di accesso che concedono all'applicazione. Pertanto, esiste una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso degli utenti. La YouTube Data API v3 utilizza i seguenti ambiti:
Il documento Ambiti API OAuth 2.0 fornisce un elenco completo degli ambiti che potresti utilizzare per accedere alle API di Google. |
||||||||||||||||
Esempi
Lo snippet seguente mostra una richiesta di esempio:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl
Questo esempio mostra un comando curl per inviare la stessa richiesta:
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
https://oauth2.googleapis.com/device/code
Passaggio 2: gestisci la risposta del server di autorizzazione
Il server di autorizzazione restituirà una delle seguenti risposte:
Risposta riuscita
Se la richiesta è valida, la risposta sarà un oggetto JSON contenente le seguenti proprietà:
| Proprietà | |
|---|---|
device_code |
Un valore assegnato da Google in modo univoco per identificare il dispositivo che esegue l'app che richiede l'autorizzazione. L'utente autorizzerà il dispositivo da un altro dispositivo con funzionalità di input più avanzate. Ad esempio, un utente potrebbe utilizzare un laptop o un cellulare per autorizzare un'app in esecuzione su una TV. In questo caso, device_code identifica la TV.
Questo codice consente al dispositivo che esegue l'app di determinare in modo sicuro se l'utente ha concesso o negato l'accesso. |
expires_in |
Il periodo di tempo, in secondi, durante il quale device_code e
user_code sono validi. Se, in questo intervallo di tempo, l'utente non completa il flusso di autorizzazione e il dispositivo non esegue anche il polling per recuperare informazioni sulla decisione dell'utente, potrebbe essere necessario riavviare la procedura dal passaggio 1. |
interval |
Il periodo di tempo, in secondi, che il dispositivo deve attendere tra una richiesta di polling e l'altra. Ad esempio, se il valore è 5, il dispositivo deve inviare una richiesta di polling al server di autorizzazione di Google ogni cinque secondi. Per ulteriori dettagli, consulta il passaggio 3. |
user_code |
Un valore sensibile alle maiuscole che identifica a Google gli ambiti a cui l'applicazione richiede l'accesso. L'interfaccia utente chiederà all'utente di inserire questo valore su un dispositivo separato con funzionalità di input più avanzate. Google utilizza quindi il valore per visualizzare l'insieme corretto di ambiti quando chiede all'utente di concedere l'accesso alla tua applicazione. |
verification_url |
Un URL a cui l'utente deve accedere su un dispositivo separato per inserire
user_code e concedere o negare l'accesso alla tua applicazione. Questo valore verrà visualizzato anche nell'interfaccia utente. |
Lo snippet seguente mostra una risposta di esempio:
{
"device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code": "GQVQ-JKEC",
"verification_url": "https://www.google.com/device",
"expires_in": 1800,
"interval": 5
}
Risposta per superamento quota
Se le richieste di codice del dispositivo hanno superato la quota associata al tuo ID client, riceverai una risposta 403, contenente il seguente errore:
{
"error_code": "rate_limit_exceeded"
}
In tal caso, utilizza una strategia di backoff per ridurre la frequenza delle richieste.
Passaggio 3: visualizza il codice utente
Mostra all'utente verification_url e user_code ottenuti nel passaggio 2. Entrambi i valori possono contenere qualsiasi carattere stampabile del set di caratteri US-ASCII. I contenuti
mostrati all'utente devono chiedere all'utente di accedere al
verification_url su un dispositivo separato e inserire il user_code.
Progetta la tua interfaccia utente (UI) tenendo presenti le seguenti regole:
user_codeuser_codedeve essere visualizzato in un campo in grado di gestire fino a 15 caratteri di dimensione "W". In altre parole, se riesci a visualizzare correttamente il codiceWWWWWWWWWWWWWWW, la tua UI è valida e ti consigliamo di utilizzare questo valore di stringa durante il test della modalità di visualizzazione diuser_codenella tua UI.user_codeè sensibile alle maiuscole e non deve essere modificato in alcun modo, ad esempio cambiando il carattere maiuscole e minuscole o inserendo altri caratteri di formattazione.
verification_url- Lo spazio in cui viene visualizzato
verification_urldeve essere sufficientemente ampio da gestire una stringa URL di 40 caratteri. - Non devi modificare in alcun modo
verification_url, tranne rimuovere facoltativamente lo schema per la visualizzazione. Se prevedi di rimuovere lo schema (ad es.https://) dall'URL per motivi di visualizzazione, assicurati che la tua app possa gestire entrambe le variantihttpehttps.
- Lo spazio in cui viene visualizzato
Passaggio 4: esegui un sondaggio sul server di autorizzazione di Google
Poiché l'utente utilizzerà un dispositivo separato per accedere alla verification_url
e concedere (o negare) l'accesso, il dispositivo richiedente non riceve automaticamente una notifica quando
l'utente risponde alla richiesta di accesso. Per questo motivo, il dispositivo richiedente deve contattare il server di autorizzazione di Google per determinare quando l'utente ha risposto alla richiesta.
Il dispositivo richiedente deve continuare a inviare richieste di polling finché non riceve una risposta
che indica che l'utente ha risposto alla richiesta di accesso o fino a quando device_code
e user_code ottenuti nel
passaggio 2 sono scaduti. Il valore interval restituito nel passaggio 2 specifica la quantità di tempo, in secondi, di attesa tra una richiesta e l'altra.
L'URL dell'endpoint del sondaggio è https://oauth2.googleapis.com/token. La richiesta di polling contiene i seguenti parametri:
| Parametri | |
|---|---|
client_id |
L'ID client dell'applicazione. Puoi trovare questo valore nella sezione API Console Credentials page. |
client_secret |
Il client secret per il valore client_id fornito. Puoi trovare questo valore nella sezione
API Console
Credentials page. |
device_code |
device_code restituito dal server di autorizzazione nel passaggio 2. |
grant_type |
Imposta questo valore su urn:ietf:params:oauth:grant-type:device_code. |
Esempi
Lo snippet seguente mostra una richiesta di esempio:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
Questo esempio mostra un comando curl per inviare la stessa richiesta:
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/token
Passaggio 5: l'utente risponde alla richiesta di accesso
L'immagine seguente mostra una pagina simile a quella che gli utenti vedono quando visitano il verification_url che hai visualizzato nel passaggio 3:
Dopo aver inserito l'user_code e, se non ha ancora eseguito l'accesso, aver eseguito l'accesso a Google,
l'utente vede una schermata di consenso come quella mostrata di seguito:
Passaggio 6: gestisci le risposte alle richieste di polling
Il server di autorizzazione di Google risponde a ogni richiesta di polling con una delle seguenti risposte:
Accesso consentito
Se l'utente ha concesso l'accesso al dispositivo (facendo clic su Allow nella schermata per il consenso),
la risposta conterrà un token di accesso e un token di aggiornamento. I token consentono al dispositivo di accedere alle API di Google per conto dell'utente. La proprietà scope nella risposta determina a quali API può accedere il dispositivo.
In questo caso, la risposta dell'API contiene i seguenti campi:
| Campi | |
|---|---|
access_token |
Il token che l'applicazione invia per autorizzare una richiesta API di Google. |
expires_in |
La durata rimanente del token di accesso in secondi. |
refresh_token |
Un token che puoi utilizzare per ottenere un nuovo token di accesso. I token di aggiornamento sono validi finché l'utente non revoca l'accesso. Tieni presente che i token di aggiornamento vengono sempre restituiti per i dispositivi. |
scope |
Gli ambiti di accesso concessi da access_token espressi come elenco di stringhe delimitate da spazi e sensibili alle maiuscole. |
token_type |
Il tipo di token restituito. Al momento, il valore di questo campo è sempre impostato su Bearer. |
Lo snippet seguente mostra una risposta di esempio:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
"token_type": "Bearer",
"refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
I token di accesso hanno una durata limitata. Se la tua applicazione ha bisogno di accedere a un'API per un lungo periodo di tempo, può utilizzare il token di aggiornamento per ottenerne uno nuovo. Se l'applicazione ha bisogno di questo tipo di accesso, deve archiviare il token di aggiornamento per un utilizzo futuro.
Accesso negato
Se l'utente si rifiuta di concedere l'accesso al dispositivo, la risposta del server ha un codice di stato della risposta HTTP 403 (Forbidden). La risposta contiene il seguente errore:
{
"error": "access_denied",
"error_description": "Forbidden"
}
In attesa di autorizzazione
Se l'utente non ha ancora completato il flusso di autorizzazione, il server restituisce un codice di stato della risposta HTTP 428 (Precondition Required). La risposta contiene il seguente errore:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
Sondaggi troppo frequenti
Se il dispositivo invia richieste di polling troppo spesso, il server restituisce un codice di stato della risposta HTTP 403 (Forbidden). La risposta contiene il seguente errore:
{
"error": "slow_down",
"error_description": "Forbidden"
}
Altri errori
Il server di autorizzazione restituisce errori anche se nella richiesta di polling mancano alcuni parametri obbligatori o se ha un valore parametro errato. Queste richieste in genere hanno un codice di stato della risposta HTTP 400
(Bad Request) o 401 (Unauthorized). Questi errori includono:
| Errore | Codice di stato HTTP | Descrizione |
|---|---|---|
admin_policy_enforced |
400 |
L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dei criteri dell'amministratore di Google Workspace. Consulta l'articolo del Centro assistenza per amministratori di Google Workspace Specificare quali app di terze parti e interne possono accedere ai dati di Google Workspace per saperne di più su come un amministratore può limitare l'accesso agli ambiti finché l'accesso non viene concesso esplicitamente al tuo ID client OAuth. |
invalid_client |
401 |
Client OAuth non trovato. Ad esempio, questo errore si verifica se il valore del parametro Il tipo di client OAuth non è corretto. Assicurati che il tipo di applicazione per l'ID client sia impostato su TV e dispositivi di input con limitazioni. |
invalid_grant |
400 |
Il valore del parametro code non è valido, è già stato rivendicato o non può essere analizzato. |
unsupported_grant_type |
400 |
Il valore del parametro grant_type non è valido. |
org_internal |
403 |
L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una specifica organizzazione Google Cloud. Conferma la configurazione del tipo di utente per la tua applicazione OAuth. |
Chiamata alle API di Google
Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API di Google per conto di un determinato account utente, se sono stati concessi gli ambiti di accesso richiesti dall'API. Per farlo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile utilizzare l'intestazione HTTP, in quanto le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, quando chiami l'API YouTube Live Streaming).
Tieni presente che l'API YouTube Live Streaming non supporta il flusso dell'account di servizio. Poiché non è possibile collegare un account di servizio a un account YouTube, i tentativi di autorizzazione delle richieste con questo flusso generano un errore NoLinkedYouTubeAccount.
Puoi provare tutte le API di Google e visualizzarne gli ambiti nel OAuth 2.0 Playground.
Esempi GET HTTP
Una chiamata all'endpoint
liveBroadcasts.list (l'API YouTube Live Streaming) che utilizza l'intestazione HTTP Authorization: Bearer
potrebbe essere simile alla seguente. Tieni presente che devi specificare un tuo token di accesso:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Ecco una chiamata alla stessa API per l'utente autenticato utilizzando il parametro della stringa di query
access_token:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl esempi
Puoi testare questi comandi con l'applicazione a riga di comando curl. Ecco un
esempio che utilizza l'opzione dell'intestazione HTTP (preferita):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Oppure, in alternativa, l'opzione del parametro della stringa di query:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Aggiornamento di un token di accesso
I token di accesso scadono periodicamente e diventano credenziali non valide per una richiesta API correlata. Se hai richiesto l'accesso offline agli ambiti associati al token, puoi aggiornare un token di accesso senza richiedere l'autorizzazione all'utente (anche quando l'utente non è presente).
Per aggiornare un token di accesso, l'applicazione invia una richiesta POST
HTTPS al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che
include i seguenti parametri:
| Campi | |
|---|---|
client_id |
L'ID client ottenuto da API Console. |
client_secret |
Il client secret ottenuto da API Console. |
grant_type |
Come definito nella specifica OAuth 2.0, il valore di questo campo deve essere impostato su refresh_token. |
refresh_token |
Il token di aggiornamento restituito dallo scambio del codice di autorizzazione. |
Lo snippet seguente mostra una richiesta di esempio:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Se l'utente non ha revocato l'accesso concesso all'applicazione, il server token restituisce un oggetto JSON contenente un nuovo token di accesso. Lo snippet seguente mostra una risposta di esempio:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"token_type": "Bearer"
}
Tieni presente che sono previsti dei limiti al numero di token di aggiornamento che verranno emessi: un limite per ogni combinazione client/utente e un altro per utente per tutti i client. Dovresti salvare i token di aggiornamento nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se l'applicazione richiede troppi token di aggiornamento, potrebbe imbattersi in questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.
Revoca di un token
In alcuni casi un utente potrebbe decidere di revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le Impostazioni account. Per ulteriori informazioni, consulta la sezione relativa alla rimozione dell'accesso di siti o app del documento di assistenza per siti e app di terze parti con accesso al tuo account.
È anche possibile che un'applicazione revoca in modo programmatico l'accesso concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione o rimuove un'applicazione oppure le risorse API richieste da un'app sono cambiate in modo significativo. In altre parole, parte del processo di rimozione può includere una richiesta API per garantire che le autorizzazioni precedentemente concesse all'applicazione vengano rimosse.
Per revocare un token in modo programmatico, l'applicazione invia una richiesta a https://oauth2.googleapis.com/revoke e include il token come parametro:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
Il token può essere un token di accesso o un token di aggiornamento. Se il token è un token di accesso e ha un token di aggiornamento corrispondente, verrà revocato anche il token di aggiornamento.
Se la revoca viene elaborata correttamente, il codice di stato HTTP della risposta è
200. Per le condizioni di errore, viene restituito un codice di stato HTTP 400 insieme a un codice di errore.
Ambiti consentiti
Il flusso OAuth 2.0 per i dispositivi è supportato solo per i seguenti ambiti:
OpenID Connect, Accedi con Google
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
API di YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly