# Najlepsze praktyki YouTube Data

Znajdź odpowiednie filmy wideo, wybierz ścieżkę podrywu i przerób nowe kanały bez powtarzania pracy.

Odniesienie kanoniczne: https://flashdata.dev/pl/docs/guides/youtube-data-guide
Przegląd: 2026-11-04 przez FlashData

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

## Zacznij od informacji, które już posiadasz

Każde źródło odpowiada na inne pytanie. Pomiń odkrycie dla znanego wideo ID lub uchwyt kanału, i wzbogacić tylko filmy wideo potrzebne zadanie.

| Twoje zadanie | Źródło | Decyzja |
| --- | --- | --- |
| Znajdź filmy o temacie | youtube_search | Zacznij od pięciu kandydatów, a następnie wybierz ze względu na znaczenie. |
| Sprawdź znany film | youtube_metadata | Uzyskaj tytuł, kanał, czas trwania i napisy językowe. |
| Podsumować lub cytować to, co powiedziano | youtube_transcript / youtube_captions | Wybierz język i ścieżkę automatyczną lub ręczną. |
| Sprawdź ostatnie kanały przesyłania | youtube_channel | Porównaj IDs z przetworzonym IDs. |

- [Znajdź filmy](https://flashdata.dev/pl/docs/guides/youtube-data-guide/reference.md#discover)
- [Praca ze znanym filmem](https://flashdata.dev/pl/docs/guides/youtube-data-guide/reference.md#metadata)
- [Monitoruj kanał](https://flashdata.dev/pl/docs/guides/youtube-data-guide/reference.md#channel)

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

## Uruchom przykłady żądania

Zapisz każde ciało JSON za pomocą wyświetlanej nazwy pliku. Python używa helpera query.py poniżej; cURL może przesłać ten sam plik. Użyj klucza z uprawnieniami źródłowymi, których potrzebujesz i dostępnymi kredytami. Każdy wniosek jest jednym pytaniem, niezależnie od liczby zwróconych filmów wideo.

### Python

Python 3.10+. Zainstaluj żądania raz, zapisz query.py poniżej, a następnie użyj polecenia obok każdego żądania. Istniejące wyjścia są ponownie używane; zmienione wejście wymaga nowej nazwy pliku wyjściowego.

#### Zainstaluj

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


### cURL

Bash. Zastąp REQUEST.json i RESULT.json nazwami plików dla wybranego przykładu. Zaznacz wynik przed powtórzeniem żądania; to polecenie zapisuje ciało HTTP nawet dla błędu.

#### Prześlij zapisane żądanie JSON

```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>

### Ustaw klawisz API

Ponownie użyj FLASHDATA_API_KEY z terminala lub tajnego sklepu. W przeciwnym razie wpisz klucz używając jednego ukrytego sygnału poniżej. Utrzymuj go w procesie, wykonując te przykłady.

#### Bash

##### Ustaw klucz

```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

##### Ustaw klucz

```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
```


- [Klucze API](https://flashdata.dev/app/api-keys)
- [Okres próbny agenta i powiązanie konta](https://flashdata.dev/pl/docs/guides/agent-onboarding/reference.md)

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

### Zapisz query.py dla przykładów Python

Utwórz query.py w nowym katalogu roboczym i skopiuj do niego cały kod poniżej. Zapisz żądanie JSON plików i innych skryptów Python w tym folderze i uruchom wszystkie polecenia stamtąd.

#### 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>

## Znajdź kandydatów przed pobraniem szczegółów

Filtr wideo wyklucza inne typy wyników; napisy zawężają odkrycia do filmów z podpisami. Nie wybiera języka napisy ani nie gwarantuje ścieżki, której potrzebujesz. Zapisz jako discover-request.json.

### discover-request.json

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

### Prześlij raz query.py

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


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

### Wybierz ze względu na znaczenie, a nie pierwszy ID

Zapisz candidates.py obok query.py i search.json, a następnie uruchom go z tego folderu. Utrzymuje kolejność wyszukiwania i usuwa duplikat wideo IDs. Sprawdź tytuły, kanały i czas trwania, a następnie skopiuj wybrany ID do następnej prośby. Pusta lista jest zakończonym wyszukiwaniem bez kandydatów.

#### 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))
```

#### Przeczytaj zapisane wyszukiwanie

```bash
python candidates.py
```


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

### Rozwiń tylko wtedy, gdy krótka lista jest niewystarczająca

Wyszukiwarka standardowa obsługuje max_results aż do 20. Dla szerszej kolekcji, przełącz na youtube_search_extended, który obsługuje do 700 i ma oddzielne ceny. Ten przykład pyta o 50; sprawdź, czy Twoje pierwsze wyniki są przydatne przed wzbogaceniem ich wszystkich.

#### extended-request.json

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

#### Biegnij raz

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

- [Prześlij dłuższe wyszukiwanie asynchronicznie](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md#async)
- [Wzbogać wybrany IDs](https://flashdata.dev/pl/docs/guides/enrich-youtube-videos/reference.md)

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

## Pobieranie tylko metadanych, których potrzebujesz

Zastąpić próbkę video_id wybranym ID. Utrzymuj format i rozdziały wyłączone dla prostej karty wideo lub podpisy-język sprawdzania. Włącz include_chapters dla konturu lub include_formats przy wyborze formatu nośnika.

### metadata-request.json

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

### Prześlij raz query.py

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

- [Pola odpowiedzi metadanych](https://flashdata.dev/pl/docs/sources/youtube_metadata/reference.md#response)
- [Przebieg prac w zakresie dostarczania nośników](https://flashdata.dev/pl/docs/guides/media-delivery-pipeline/reference.md)

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

### Sprawdź dostępne języki

Przeczytaj wyniki [0] .transcriptLanguages przed wybraniem napisów. Formaty, rozdziały i języki są polami zwróconego obiektu wideo; zapis użycia należy do odpowiedzi zewnętrznej.

| Ustawienie | Użyj go do |
| --- | --- |
| language | Kod transcriptLanguages, takich jak en lub zh- Hans. Lista ta nie wyróżnia ręcznych i automatycznych torów. |
| auto: true | Istniejący automatycznie generowany utwór. |
| auto: false | Istniejący ręczny utwór. Między dwoma typami torów nie ma odwrotu. |

#### Przeczytaj metadata.json · bez zapytania

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


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

## Wybierz język i śledzić wyraźnie

Użyj tego samego video_id, co żądasz metadanych, a także zmień język i auto, aby dopasować wybrany utwór. youtube_transcript domyślnie pasuje do auto: true; youtube_captions domyślnie do auto: false. Obie pobierają istniejące podpisy, a nie przekaz do tekstu.

### captions-request.json

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

### Prześlij raz query.py

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

- [Parametry przechwytywania](https://flashdata.dev/pl/docs/sources/youtube_transcript/reference.md#parameters)
- [Zbuduj pełne podsumowanie](https://flashdata.dev/pl/docs/guides/youtube-summary/reference.md)

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

### Zatrzymaj znacznik czasu wraz z dowodami

Zapisz cite-segments.py obok captions.json i uruchom go z tego folderu. Użyj wyników [0] .segmenty dla cytowania: start i koniec są sekundami. Zachować languageCode i isAutoGenerated z tekstem. fullText jest przydatny do odczytu, ale nie zastępuje czasu segmentu. Jeśli wybrana ścieżka jest brakująca, zapisz lukę przed podjęciem decyzji, czy inne zapytanie jest warte zachodu.

#### 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)
```

#### Odczyt zapisanych napisów · bez wywołania API

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


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

## Przetwarzanie tylko nowych filmów ze znanego kanału

Użyj uchwytu kanału i ograniczonego video_limit (1–100). Rezultaty [0] .Video to zwrócona lista; videoCount to metadane kanału, a nie liczba zwróconych elementów. Wybierz limit i harmonogram, który obejmuje pliki, które należy obserwować.

### channel-request.json

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

### Prześlij raz query.py

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


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

### Zachowaj kolejkę i punkt kontrolny zakończenia

Zapisz channel-queue.py obok query.py i channel.json i uruchom go z tego folderu. Uruchom bez argumentów, aby utworzyć new-ids.json, a następnie przetworzyć i zapisać dowody dla tych IDs. Uruchom --commit tylko po każdym sukcesie kolejki ID; awaria pozostawia punkt kontrolny bez zmian. Użyj jednego katalogu na kanał i jednego pracownika dla tego przykładu.

#### 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))
```

#### Plan → proces → commit

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

- [Dane identyfikacyjne dotyczące harmonogramu i ponownego użycia](https://flashdata.dev/pl/docs/guides/recurring-tasks/reference.md)
- [Wzbogacenie listy filmów wideo](https://flashdata.dev/pl/docs/guides/enrich-youtube-videos/reference.md)

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

### Rozpocząć sprawdzanie kanału z premedytacją

Pomocnik zapytania ponownie używa zapisanej odpowiedzi. Dla następnej planowej kontroli, użyj nowej nazwy pliku wyniku, sprawdź go, a następnie skopiuj, który zakończył odpowiedź na channel.json dla kroku kolejki. Zachowaj processed-ids.json pomiędzy biegami. Ten ostatni wykaz nie jest pełnokanałowym eksportem ani strumieniem zdarzeń.

#### Następna kontrola · wybierz świeżą nazwę pliku

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

#### Po potwierdzeniu statusu jest wykonane

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


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

## Użyj sugestii, aby poprawić zapytanie

Sugeruje zwrot zwrotów w wynikach [0], a nie nagrania wideo. Wybierz przydatne zdanie i zrób osobne youtube_search żądanie. Ustaw język i region dla publiczności, którą badasz.

### suggestions-request.json

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

### Prześlij raz query.py

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


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

## Przechowywanie etykiet licencyjnych bez traktowania ich jako zezwolenia

youtube_trainability zwraca etykietę licencyjną dla wideoo. dozwolone: ["all"] maps to Creative Commons; ["none"] obejmuje również brakujące metadane licencji. Zachowaj wideo ID, odpowiedź źródła i datę pobrania. Niniejsza etykieta nie przyznaje praw do pobierania, ponownego wykorzystywania lub szkolenia.

### license-request.json

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

### Prześlij raz query.py

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


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

## Ogranicza pracę dla aplikacji i agentów

| Artykuł | Wykonanie |
| --- | --- |
| Wybierz przed wzbogaceniem | Dla zadania tematycznego: jedno wyszukiwanie, jeden wybrany metadane wideo i jeden wybrany utwór podsumowujący. Wymuszanie budżetu połączeń w aplikacji i cena każdego źródła oddzielnie. |
| Ponowne wykorzystanie przez rzeczywisty wkład | Metadane: opcje wideo ID +. Podpisy: wideo ID + język + utwór. Migawki kanału również potrzebują czasu pobierania lub uruchomić ID. |
| Zatrzymaj brakujące dowody | Nie należy ponownie próbować pustego wyniku wyszukiwania lub po cichu przełączać śladów nagrywania. Zwróć lukę, aby użytkownik lub przepływ pracy mógł wybrać następne działanie. |
| Zachowanie użytkowania i nieudanej pracy | Zapisz użycie z udanych odpowiedzi. Na 429, honor Retry-After; po niepewnym zgłoszeniu, sprawdzić History przed innym płatnym zapytaniem. |

- [Realtime i async](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md)
- [Batch i luzem](https://flashdata.dev/pl/docs/reference/batch-and-bulk/reference.md)
- [Błędy i powtórzenia](https://flashdata.dev/pl/docs/errors/reference.md#retries)
- [Obecne ceny i saldo](https://flashdata.dev/pl/docs/guides/credits-and-billing/reference.md)
