# YouTube Migliori pratiche di dati

Trova i video pertinenti, seleziona le tracce didascalia e elabora nuovi upload dei canali senza ripetere il lavoro.

Riferimento canonico: https://flashdata.dev/it/docs/guides/youtube-data-guide
Recensito: 2026-11-04 da FlashData

<a id="choose"></a>

## Inizia con le informazioni che hai già

Ogni fonte risponde a una domanda diversa. Salta la scoperta per un noto video ID o maniglia del canale, e arricchisci solo i video di cui hai bisogno.

| Il tuo compito | Fonte | Decisione |
| --- | --- | --- |
| Trova i video su un argomento | youtube_search | Iniziare con cinque candidati, quindi selezionare per importanza. |
| Ispezione di un video noto | youtube_metadata | Ottieni il titolo, il canale, la durata e le lingue didascalia. |
| Summarizzare o citare ciò che è stato detto | youtube_transcript / youtube_captions | Scegli una lingua e una traccia automatica o manuale. |
| Controllare gli upload recenti del canale | youtube_channel | Confronta IDs restituito con il tuo IDs processato. |

- [Trova i video](https://flashdata.dev/it/docs/guides/youtube-data-guide/reference.md#discover)
- [Lavorare con un video conosciuto](https://flashdata.dev/it/docs/guides/youtube-data-guide/reference.md#metadata)
- [Monitorare un canale](https://flashdata.dev/it/docs/guides/youtube-data-guide/reference.md#channel)

<a id="setup"></a>

## Eseguire gli esempi di richiesta

Salvare ogni corpo JSON utilizzando il nome del file visualizzato. Python utilizza l'helper query.py qui sotto; cURL può inviare lo stesso file. Utilizzare una chiave con le autorizzazioni di origine di cui hai bisogno e i crediti disponibili. Ogni presentazione è una domanda, indipendentemente dal numero di video restituiti.

### Python

Python 3.10+. Installare le richieste una volta, salvare query.py di seguito, quindi utilizzare il comando accanto a ogni richiesta. Le uscite esistenti vengono riutilizzate; l'ingresso modificato richiede un nuovo nome di file di output.

#### Installa

```bash
python -m pip install requests
```


### cURL

Bash. Sostituisci REQUEST.json e RESULT.json con i nomi dei file per l'esempio scelto. Controllare il risultato prima di ripetere una richiesta; questo comando salva il corpo HTTP anche per un errore.

#### Invia una richiesta di JSON salvata

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @REQUEST.json --output RESULT.json
)
```



<a id="authenticate"></a>

### Impostare il tasto API

Riutilizza FLASHDATA_API_KEY dal tuo terminale o negozio segreto. In caso contrario, inserire la chiave utilizzando un prompt nascosto qui sotto. Mantenere il processo di esecuzione di questi esempi.

#### Bash

##### Impostare la chiave

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Impostare la chiave

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [chiavi API](https://flashdata.dev/app/api-keys)
- [Prova per agenti e collegamento](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md)

<a id="runner"></a>

### Salvare query.py per gli esempi Python

Crea query.py in una nuova cartella di lavoro e copia il codice completo qui sotto. Salvare la richiesta di file JSON e altri script Python in questa cartella e eseguire tutti i comandi da lì.

#### query.py

```python
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))
```


<a id="discover"></a>

## Trova i candidati prima di ottenere i dettagli

Il filtro video esclude altri tipi di risultati; sottotitoli restringe la scoperta ai video con didascalie. Non seleziona una lingua didascalia o garantisce la traccia di cui hai bisogno. Salva come discover-request.json.

### discover-request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
```

### Invia una volta con query.py

```bash
python query.py discover-request.json search.json
```


<a id="candidates"></a>

### Selezionare per rilevanza, non il primo ID

Salvare candidates.py accanto a query.py e search.json, quindi eseguirlo da quella cartella. Mantiene l'ordine di ricerca e rimuove il video duplicato IDs. Ispezionare i titoli, i canali e la durata, quindi copiare un ID selezionato nella prossima richiesta. Una lista vuota è una ricerca completa senza candidati.

#### candidates.py

```python
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
```

#### Leggi la ricerca salvata

```bash
python candidates.py
```


<a id="extended"></a>

### Espandi solo quando la lista corta è insufficiente

Standard Search supporta max_results fino a 20. Per una raccolta più ampia, passare a youtube_search_extended, che supporta fino a 700 e ha prezzi separati. Questo esempio chiede 50; controlla se i primi risultati sono utili prima di arricchirli tutti.

#### extended-request.json

```json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
```

#### Scappa una volta

```bash
python query.py extended-request.json extended.json
```

- [Inviare una ricerca più lunga in modo asincrono](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#async)
- [Arricchire IDs](https://flashdata.dev/it/docs/guides/enrich-youtube-videos/reference.md)

<a id="metadata"></a>

## Recuperare solo i metadati di cui hai bisogno

Sostituisci il campione video_id con il tuo ID selezionato. Mantenere formati e capitoli disabilitati per una semplice scheda video o controllo in lingua didascalia. Abilitare include_chapters per un profilo, o include_formats quando si sceglie un formato multimediale.

### metadata-request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```

### Invia una volta con query.py

```bash
python query.py metadata-request.json metadata.json
```

- [Campi di risposta ai metadati](https://flashdata.dev/it/docs/sources/youtube_metadata/reference.md#response)
- [Flusso di lavoro di consegna media](https://flashdata.dev/it/docs/guides/media-delivery-pipeline/reference.md)

<a id="tracks"></a>

### Ispezione delle lingue disponibili

Leggi i risultati[0].transcriptLanguages prima di scegliere le didascalie. Formati, capitoli e lingue sono campi sull'oggetto video restituito; il record di utilizzo appartiene alla risposta esterna.

| Impostazione | Usalo per |
| --- | --- |
| language | Un codice da transcriptLanguages, come en o zh-Hans. Questa lista non distingue le tracce manuali e automatiche. |
| auto: true | Una traccia generata automaticamente esistente. |
| auto: false | Una traccia fornita manualmente esistente. Non c'è alcun ritorno tra i due tipi di traccia. |

#### Leggi metadata.json · nessuna query

```bash
python -m json.tool metadata.json
```


<a id="captions"></a>

## Scegli la lingua e traccia esplicitamente

Utilizzare lo stesso video_id come la vostra richiesta di metadati e cambiare lingua e auto per abbinare la traccia scelta. youtube_transcript di default per l'auto: true; youtube_captions di default per l'auto: false. Entrambi recuperano le didascalie esistenti, non parole-to-text.

### captions-request.json

```json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

### Invia una volta con query.py

```bash
python query.py captions-request.json captions.json
```

- [Parametri di acquisizione](https://flashdata.dev/it/docs/sources/youtube_transcript/reference.md#parameters)
- [Costruisci un sommario completo](https://flashdata.dev/it/docs/guides/youtube-summary/reference.md)

<a id="citations"></a>

### Tenere il timestamp con le prove

Salvare cite-segments.py accanto a captions.json ed eseguirlo da quella cartella. Utilizzare i risultati[0].segmenti per le citazioni: inizio e fine sono secondi. Conservare languageCode e isAutoGenerated con il testo. fullText è utile per la lettura, ma non sostituisce la tempistica del segmento. Se la traccia scelta manca, registra il divario prima di decidere se vale un'altra domanda.

#### cite-segments.py

```python
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
```

#### Leggi le didascalie salvate · no API

```bash
python cite-segments.py
```


<a id="channel"></a>

## Elabora solo nuovi video da un canale noto

Utilizzare una maniglia del canale e un limitato video_limit (1–100). risultati[0].videos è l'elenco recente restituito; videoCount è metadati del canale, non il numero di elementi restituiti. Scegli un limite e un calendario che coprano i caricamenti che devi osservare.

### channel-request.json

```json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
```

### Invia una volta con query.py

```bash
python query.py channel-request.json channel.json
```


<a id="channel-diff"></a>

### Mantenere una coda e un checkpoint di completamento

Salvare channel-queue.py accanto a query.py e channel.json, ed eseguirlo da quella cartella. Eseguire senza argomenti per creare new-ids.json, quindi elaborare e salvare le prove per quelle IDs. Eseguire --commit solo dopo che ogni coda ID riesce; un guasto lascia il punto di controllo invariato. Utilizzare una directory per canale e un lavoratore per questo esempio.

#### channel-queue.py

```python
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
```

#### Piani → processo → commit

```bash
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit
```

- [Programma e riutilizza le credenziali](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)
- [Arricchire un elenco di video](https://flashdata.dev/it/docs/guides/enrich-youtube-videos/reference.md)

<a id="channel-checkpoint"></a>

### Avviare un controllo del canale fresco deliberatamente

Il query helper riutilizza una risposta salvata. Per il successivo controllo programmato, utilizzare un nuovo nome di file di risultato, ispezionarlo, quindi copiare quella risposta completa a channel.json per la fase di coda. Tenere processed-ids.json tra le piste. Questo elenco recente non è un'esportazione a pieno canale o un flusso di eventi.

#### Prossimo controllo · scegliere un nome di file fresco

```bash
python query.py channel-request.json channel-next.json
```

#### Dopo aver confermato lo stato è fatto

```bash
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"
```


<a id="suggestions"></a>

## Utilizzare i suggerimenti per migliorare la query

Suggerimenti restituiscono frasi nei risultati[0], non record video. Selezionare una frase utile e fare una richiesta youtube_search separata. Impostare la lingua e la regione per il pubblico che si sta ricercando.

### suggestions-request.json

```json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
```

### Invia una volta con query.py

```bash
python query.py suggestions-request.json suggestions.json
```


<a id="license"></a>

## Archiviare etichette di licenza senza trattarle come permesso

youtube_trainability restituisce un'etichetta di licenza per un video. permesso: ["all"] mappe a Creative Commons; ["none"] copre anche i metadati di licenza mancanti. Tenere il video ID, risposta di origine e data di recupero. Questa etichetta non concede diritti di download, riutilizzo o formazione.

### license-request.json

```json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
```

### Invia una volta con query.py

```bash
python query.py license-request.json license.json
```


<a id="operations"></a>

## Creare il lavoro per applicazioni e agenti

| Articolo | Atto |
| --- | --- |
| Selezionare prima di arricchire | Per un'attività di argomento: una ricerca, un metadati selezionati del video e una traccia di didascalia scelta. Applicare il budget delle chiamate nella tua app e il prezzo di ogni fonte separatamente. |
| Riutilizzo da parte dell'ingresso effettivo | Metadati: video ID + opzioni. Didascalie: video ID + lingua + traccia. Le snapshot del canale hanno anche bisogno di un tempo di recupero o di eseguire ID. |
| Smettere di mancare di prove | Non riprovare un risultato di scoperta vuoto o commutare silenziosamente le tracce di didascalia. Restituire il gap in modo che l'utente o il flusso di lavoro possano scegliere l'azione successiva. |
| Conservare l'uso e il lavoro fallito | Salvare l'uso con risposte di successo. Su 429, onore Retry-After; dopo una presentazione incerta, controllare History prima di un'altra domanda a pagamento. |

- [Realtime e asincrona](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md)
- [Batch e rinfuse](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md)
- [Errori e ritiri](https://flashdata.dev/it/docs/errors/reference.md#retries)
- [Prezzi e saldo correnti](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md)
