Panoramica dell'API di dati di YouTube

Introduzione

Questo documento è rivolto agli sviluppatori che desiderano scrivere applicazioni che interagiscano con YouTube. Illustra i concetti di base di YouTube e dell'API stessa. Fornisce inoltre una panoramica delle diverse funzioni supportate dall'API.

Prima di iniziare

1. Devi avere un Account Google per accedere alla console API di Google, richiedere una chiave API e registrare la tua applicazione.

2. Crea un progetto in Google Developers Console e ottieni le credenziali di autorizzazione per consentire alla tua applicazione di inviare richieste API.

3. Dopo aver creato il progetto, assicurati che l'API di dati di YouTube sia uno dei servizi per cui la tua applicazione è registrata:

   1. Vai alla console API e seleziona il progetto che hai appena registrato.
   2. Visita la pagina API abilitate. Nell'elenco delle API, assicurati che lo stato della YouTube Data API v3 sia impostato su ON.

4. Se la tua applicazione utilizzerà metodi dell'API che richiedono l'autorizzazione utente, leggi la guida per l'autenticazione per imparare a implementare l'autorizzazione OAuth 2.0.

5. Seleziona una libreria client per semplificare l'implementazione dell'API.

6. Acquisisci familiarità con i concetti fondamentali del formato dati JSON (JavaScript Object Notation). JSON è un formato di dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture di dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.

Risorse e tipi di risorse

Una risorsa è una singola entità di dati con un identificatore univoco. La tabella seguente descrive i diversi tipi di risorse con cui puoi interagire utilizzando l'API.

Tieni presente che, in molti casi, una risorsa contiene riferimenti ad altre risorse. Ad esempio, la proprietà snippet.resourceId.videoId di una risorsa playlistItem identifica una risorsa video che, a sua volta, contiene informazioni complete sul video. Per fare un altro esempio, un risultato di ricerca contiene una proprietà videoId, playlistId o channelId che identifica un determinato video, playlist o risorsa del canale.

Operazioni supportate

La tabella seguente mostra i metodi più comuni supportati dall'API. Alcune risorse supportano anche altri metodi che eseguono funzioni più specifiche per queste risorse. Ad esempio, il metodo videos.rate associa la valutazione di un utente a un video, mentre il metodo thumbnails.set carica un'immagine in miniatura del video su YouTube e la associa a un video.

L'API attualmente supporta metodi per elencare ciascuno dei tipi di risorse supportati e supporta anche le operazioni di scrittura per molte risorse.

La tabella seguente identifica le operazioni supportate per i diversi tipi di risorse. Le operazioni che inseriscono, aggiornano o eliminano risorse richiedono sempre l'autorizzazione dell'utente. In alcuni casi, i metodi list supportano le richieste sia autorizzate che non autorizzate, dove quelle non autorizzate recuperano solo i dati pubblici, mentre le richieste autorizzate possono anche recuperare informazioni relative all'utente attualmente autenticato o informazioni private per l'utente attualmente autenticato.

Utilizzo della quota

YouTube Data API utilizza una quota per garantire che gli sviluppatori utilizzino il servizio come previsto e non creare applicazioni che riducono ingiustamente la qualità del servizio o limitano l'accesso per altri utenti. Tutte le richieste API, incluse quelle non valide, comportano un costo di quota di almeno un punto. Puoi trovare la quota disponibile per la tua applicazione nel API Console.

I progetti che abilitano l'API YouTube Data hanno una quota predefinita assegnata di 10.000 unità al giorno, un importo sufficiente per la stragrande maggioranza degli utenti dell'API. La quota predefinita, che è soggetta a modifiche, ci aiuta a ottimizzare l'allocazione delle quote e a scalare la nostra infrastruttura in modo più significativo per gli utenti dell'API. Puoi visualizzare l'utilizzo della quota nella pagina Quote della console API.

Nota: se raggiungi il limite della quota, puoi richiedere una quota aggiuntiva per completare l'estensione della quota modulo di richiesta per i servizi API di YouTube.

Calcolo dell'utilizzo della quota

Google calcola l'utilizzo della quota assegnando un costo a ogni richiesta. Diversi tipi di operazioni hanno costi di quota diversi. Ad esempio:

• Un'operazione di lettura che recupera un elenco di risorse (canali, video, playlist) costa 1 unità.
• Un'operazione di scrittura che crea, aggiorna o elimina una risorsa di solito ha dei costi 50 unità.
• Una richiesta di ricerca costa 100 unità.
• Il caricamento di un video costa 1600 unità.

La tabella Costi di quota per le richieste API mostra le costo quota di ogni metodo API. Tenendo presenti queste regole, puoi stimare il numero di richieste che la tua applicazione può inviare al giorno senza superare la quota.

Risorse parziali

L'API consente, e richiede effettivamente, il recupero di risorse parziali in modo che le applicazioni evitino il trasferimento, l'analisi e l'archiviazione di dati non necessari. Questo approccio garantisce anche che l'API utilizzi le risorse di rete, CPU e memoria in modo più efficiente.

L'API supporta due parametri di richiesta, descritti nelle sezioni seguenti, che consentono di identificare le proprietà delle risorse da includere nelle risposte dell'API.

• Il parametro part identifica i gruppi di proprietà che devono essere restituiti per una risorsa.
• Il parametro fields filtra la risposta dell'API in modo che restituisca solo proprietà specifiche all'interno delle parti delle risorse richieste.

Come utilizzare il parametro part

Il parametro part è obbligatorio per qualsiasi richiesta API che recupera o restituisce una risorsa. Il parametro identifica una o più proprietà di risorsa di primo livello (non nidificate) che devono essere incluse in una risposta dell'API. Ad esempio, una risorsa video ha le seguenti parti:

• snippet
• contentDetails
• fileDetails
• player
• processingDetails
• recordingDetails
• statistics
• status
• suggestions
• topicDetails

Tutte queste parti sono oggetti che contengono proprietà nidificate, che si possono considerare come gruppi di campi di metadati che il server API potrebbe (o non potrebbe) recuperare. Di conseguenza, il parametro part richiede di selezionare i componenti delle risorse effettivamente utilizzati dalla tua applicazione. Questo requisito ha due scopi fondamentali:

• Riduce la latenza impedendo al server API di dedicare del tempo al recupero dei campi di metadati non utilizzati dalla tua applicazione.
• Consente di ridurre l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che l'applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungeranno più parti, questi vantaggi aumenteranno solo in quanto la tua applicazione non richiederà proprietà introdotte di recente che non supporta.

Come utilizzare il parametro fields

Il parametro fields filtra la risposta dell'API, che contiene solo le parti della risorsa identificate nel valore del parametro part, in modo che la risposta includa solo un insieme specifico di campi. Il parametro fields consente di rimuovere le proprietà nidificate da una risposta dell'API e quindi di ridurre ulteriormente l'utilizzo della larghezza di banda. Il parametro part non può essere utilizzato per filtrare le proprietà nidificate di una risposta.

Le seguenti regole spiegano la sintassi supportata per il valore del parametro fields, che è basata sulla sintassi XPath:

• Utilizza un elenco separato da virgole (fields=a,b) per selezionare più campi.
• Utilizza un asterisco (fields=*) come carattere jolly per identificare tutti i campi.
• Utilizza le parentesi (fields=a(b,c)) per specificare un gruppo di proprietà nidificate che sarà incluso nella risposta dell'API.
• Utilizza una barra (fields=a/b) per identificare una proprietà nidificata.

In pratica, queste regole spesso consentono a diversi valori parametro fields di recuperare la stessa risposta API. Ad esempio, se vuoi recuperare l'ID, il titolo e la posizione degli elementi di una playlist per ogni elemento di una playlist, puoi utilizzare uno qualsiasi dei seguenti valori:

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
• fields=items(id,snippet/title,snippet/position)
• fields=items(id,snippet(title,position))

Nota: come per tutti i valori dei parametri di query, il valore parametro fields deve essere codificato nell'URL. Per una migliore leggibilità, gli esempi in questo documento omettono la codifica.

Esempi di richieste parziali

Gli esempi riportati di seguito mostrano come utilizzare i parametri part e fields per garantire che le risposte dell'API includano solo i dati utilizzati dall'applicazione:

1. L'esempio 1 restituisce una risorsa video che include quattro parti e le proprietà kind e etag.
2. L'esempio 2 restituisce una risorsa video che include due parti e le proprietà kind e etag.
3. L'esempio 3 restituisce una risorsa video che include due parti ma esclude le proprietà kind e etag.
4. L'esempio 4 restituisce una risorsa video che include due parti ma esclude kind e etag, nonché alcune proprietà nidificate nell'oggetto snippet della risorsa.

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

Ottimizzazione del rendimento

Accept-Encoding: gzip
User-Agent: my program (gzip)