Panoramica dell'API YouTube Data

Introduzione

Questo documento è destinato agli sviluppatori che intendono scrivere applicazioni che interagiscano con YouTube. Illustra i concetti basilari di YouTube e dell'API stessa. Offre inoltre una panoramica delle diverse funzioni supportate dall'API.

Prima di iniziare

1. Per accedere alla Console delle API di Google, richiedere una chiave API e registrare l'applicazione è necessario avere un Account Google.

2. Crea un progetto in Google Developers Console e ottieni le credenziali di autorizzazione in modo che la tua applicazione possa inviare richieste API.

3. Dopo aver creato il progetto, assicurati che l'API YouTube Data sia uno dei servizi registrati dalla tua applicazione:

   1. Vai alla Console API e seleziona il progetto che hai appena registrato.
   2. Visita la pagina relativa alle API abilitate. Nell'elenco delle API, assicurati che lo stato sia ON per la API YouTube Data v3.

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 dati comune indipendente dal linguaggio che fornisce una semplice rappresentazione testuale delle strutture di dati arbitrari. Per ulteriori informazioni, visita il sito json.org.

Risorse e tipi di risorse

Una risorsa è una singola entità 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. Come ulteriore esempio, un risultato di ricerca contiene una proprietà videoId, playlistId o channelId che identifica una determinata risorsa video, playlist o canale.

Operazioni supportate

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

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

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

Utilizzo quota

YouTube Data API utilizza una quota per garantire che gli sviluppatori utilizzino il servizio come previsto e non creino applicazioni che riducono ingiustamente la qualità del servizio o ne limitano l'accesso ad altri. Per tutte le richieste API, incluse quelle non valide, è previsto un costo relativo alla quota di almeno un punto. Puoi trovare la quota disponibile per la tua applicazione in API Console.

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

Nota: se raggiungi il limite di quota, puoi richiedere una quota aggiuntiva compilando il modulo di richiesta di estensione di quota per i Servizi API di YouTube.

Calcolo dell'utilizzo della quota

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

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

La tabella Costi delle quote per richieste API mostra il costo della quota di ogni metodo API. Tenendo presenti queste regole, puoi stimare il numero di richieste che la tua applicazione potrebbe inviare ogni giorno senza superare la quota.

Risorse parziali

L'API consente, e in realtà richiede, il recupero di risorse parziali in modo che le applicazioni non trasferiscano, analizzino e archivino dati non necessari. Questo approccio garantisce inoltre che l'API utilizzi le risorse di rete, CPU e di memoria in modo più efficiente.

L'API supporta due parametri di richiesta, illustrati nelle sezioni seguenti, che consentono di identificare le proprietà della risorsa 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 API in modo che restituisca solo proprietà specifiche all'interno delle parti della risorsa richieste.

Come utilizzare il parametro part

Il parametro part è un parametro obbligatorio per qualsiasi richiesta API che recupera o restituisce una risorsa. Il parametro identifica una o più proprietà delle risorse di primo livello (non nidificate) che devono essere incluse in una risposta 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 e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o non dovrebbe) recuperare. Pertanto, il parametro part richiede la selezione dei componenti di risorse effettivamente utilizzati dalla tua applicazione. Questo requisito ha due scopi principali:

• Riduce la latenza impedendo al server API di perdere tempo per recuperare i campi di metadati che la tua applicazione non utilizza.
• Riduce l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che la tua applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungono altre parti, questi vantaggi aumenteranno solo perché la tua applicazione non richiederà proprietà appena introdotte che non supportano.

Come utilizzare il parametro fields

Il parametro fields filtra la risposta API, che contiene solo le parti della risorsa identificate nel valore 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 API, riducendo così l'utilizzo della larghezza di banda. Il parametro part non può essere utilizzato per filtrare le proprietà nidificate da una risposta.

Le seguenti regole spiegano la sintassi supportata per il valore parametro fields, che si basa su una sintassi di 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 verranno incluse nella risposta API.
• Utilizza una barra (fields=a/b) per identificare una proprietà nidificata.

In pratica, queste regole consentono spesso diversi valori parametro fields per recuperare la stessa risposta API. Ad esempio, se vuoi recuperare l'ID, il titolo e la posizione di ogni elemento della playlist, puoi utilizzare uno 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 ricerca, il valore del parametro fields deve essere codificato tramite URL. Per una migliore leggibilità, gli esempi in questo documento omettono la codifica.

Richieste parziali di esempio

I seguenti esempi mostrano come utilizzare i parametri part e fields per assicurare 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 delle prestazioni

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