# YouTube Dataベストプラクティス

関連するビデオを見つけ、キャプショントラックを選択し、作業を繰り返すことなく新しいチャネルのアップロードを処理します。

キャニシニカル参照: https://flashdata.dev/ja/docs/guides/youtube-data-guide
レビュー: FlashData による 2026-11-04

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

## 既に持っている情報から始めましょう。

各ソースは、異なる質問に答えます。 既知のビデオIDまたはチャネルハンドルの発見をスキップし、あなたのタスクのニーズのビデオだけを豊かにします。

| あなたのタスク | ソース | デコレーション |
| --- | --- | --- |
| トピックに関する動画を探す | youtube_search | 5つの候補からスタートし、関連性で選択します。 |
| 既知の動画を調べる | youtube_metadata | タイトル、チャンネル、期間、およびキャプション言語を取得します。 |
| 召されたものを恥ずかしがりかしがらせるか、または叫びなさい | youtube_transcript / youtube_captions | 言語と自動または手動のトラックを選択します。 |
| 最近のチャンネルのアップロードをチェック | youtube_channel | 処理したIDsで返されたIDsを比較します。 |

- [ビデオを探す](https://flashdata.dev/ja/docs/guides/youtube-data-guide/reference.md#discover)
- [既知のビデオで作業](https://flashdata.dev/ja/docs/guides/youtube-data-guide/reference.md#metadata)
- [チャネルを監視する](https://flashdata.dev/ja/docs/guides/youtube-data-guide/reference.md#channel)

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

## リクエスト例のリクエストを実行する

表示されたファイル名を使用して、各 JSON ボディを保存します。 Python は、以下の query.py ヘルパーを使用します。 cURL は同じファイルを送信できます。 必要なクレジットと利用可能なクレジットのソース権限でキーを使用します。 各投稿は、返された動画の数に関係なく、ひとつのクエリです。

### Python

Python 3.10+。 リクエストを一度インストールし、下にあるquery.pyを保存し、各リクエストの横にあるコマンドを使用します。 既存の出力は再利用されます。変更された入力には新しい出力ファイル名が必要です。

#### インストール

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


### cURL

Bash.の特長 REQUEST.jsonとRESULT.jsonを、選択した例のファイル名に置き換えます。 リクエストを繰り返す前に結果を確認してください。このコマンドは、エラーに対してもHTTPボディを保存します。

#### 保存した 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>

### APIキーを設定する

端末やシークレットストアから FLASHDATA_API_KEY を再利用します。 それ以外の場合は、下の1つの隠しプロンプトを使用してキーを入力してください。 これらの例を実行しているプロセスに保管してください。

#### Bash

##### キーを設定する

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

##### キーを設定する

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


- [APIキー](https://flashdata.dev/app/api-keys)
- [エージェントの試用とアカウント連携](https://flashdata.dev/ja/docs/guides/agent-onboarding/reference.md)

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

### Python の例の query.py を保存

query.py を新しい作業フォルダに作成し、以下の完全なコードをコピーします。 リクエストを保存 JSON ファイル等 Python このフォルダー内のスクリプト、そこからすべてのコマンドを実行します。

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

## 詳細については取得する前に候補を見つける

ビデオフィルタは、他の結果タイプを除外します。字幕は、キャプション付きのビデオに発見を絞り込みます。 必要なトラックをキャプション言語を選択するか、保証しません。 discover-request.jsonとして保存します。

### discover-request.json

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

### query.pyで一度に提出する

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


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

### ID ではなく、関連性で選択

query.py と search.json の横にある candidates.py を保存し、そのフォルダから実行します。 検索順序を保持し、重複したビデオIDsを削除します。 タイトル、チャンネル、期間を調べて、選択したIDを次のリクエストにコピーします。 空のリストは候補無しで完全な検索です。

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

#### 保存された検索を読む

```bash
python candidates.py
```


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

### ショートリストが不十分な場合にのみ拡大

20までの標準検索はmax_resultsをサポートしています。 700まで対応するyoutube_search_extendedに切り替えて、別々の価格設定をしています。 この例では、50 を要求します。最初の結果は、それらをすべて強化する前に有用であるかを確認してください。

#### extended-request.json

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

#### 一度走る

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

- [より長い検索を非同期に送信する](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md#async)
- [Enrich 選択 IDs](https://flashdata.dev/ja/docs/guides/enrich-youtube-videos/reference.md)

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

## 機能が必要とするメタデータだけを取得する

サンプルを取り替えて下さい video_id 選択した ID. シンプルなビデオカードまたはキャプション言語チェックのために、フォーマットとチャプターを無効に保ちます。 include_chapters をアウトラインで有効化したり、include_formats をメディアフォーマットを選択するときに有効化します。

### metadata-request.json

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

### query.pyで一度に提出する

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

- [メタデータ応答フィールド](https://flashdata.dev/ja/docs/sources/youtube_metadata/reference.md#response)
- [メディア配信ワークフロー](https://flashdata.dev/ja/docs/guides/media-delivery-pipeline/reference.md)

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

### 利用可能な言語を調べる

結果を読む[0].transcriptLanguagesは、キャプションを選択する前に. フォーマット、チャプター、言語は、返されたビデオオブジェクトのフィールドです。使用記録は、外部応答に属します。

| セットアップ | 利用する |
| --- | --- |
| language | transcriptLanguagesのコードは、enやzh-Hansなどのコードです。 このリストは、マニュアルと自動トラックを区別しません。 |
| auto: true | 既存の自動生成されたトラック。 |
| auto: false | 既存の手動で提供されるトラック。 2つのトラックタイプのフォールバックはありません。 |

#### metadata.json を読んで下さい ·照会無し

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


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

## 言語を選択し、明示的に追跡します

同じ video_id をメタデータリクエストとして使用し、言語と自動を変更して、選択したトラックと一致させます。 youtube_transcript のデフォルトは auto: true です。 youtube_captions のデフォルトは auto: false です。 両方とも、既存のキャプションを、スピーチからテキストまで取得します。

### captions-request.json

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

### query.pyで一度に提出する

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

- [キャプションパラメータ](https://flashdata.dev/ja/docs/sources/youtube_transcript/reference.md#parameters)
- [完全な要約を作成する](https://flashdata.dev/ja/docs/guides/youtube-summary/reference.md)

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

### 証拠でタイムスタンプを保ちましょう

captions.jsonの横にあるcite-segments.pyを保存し、そのフォルダから実行します。 引用のための結果[0].segmentsを使用して下さい:開始および端は秒です。 languageCodeとisAutoGeneratedをテキストで保存します。 fullTextは読書に便利ですが、セグメントのタイミングを交換しません。 選択したトラックが見つからない場合、別のクエリが値するかどうかを決定する前のギャップを記録します。

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

#### 保存されたキャプションを読む · API コールなし

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


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

## 既知のチャンネルから新しい動画のみを処理する

チャンネルハンドルとバインドされたvideo_limit(1–100)を使用します。結果[0].ビデオは、返された最近のリストです。 videoCountは、返された項目の数ではなく、チャネルメタデータです。 あなたが観察する必要があるアップロードをカバーする制限とスケジュールを選択します。

### channel-request.json

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

### query.pyで一度に提出する

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


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

### キューと完了チェックポイントを保ちましょう

query.py と channel.json の横にある channel-queue.py を保存し、そのフォルダから実行します。 new-ids.jsonを作成するための引数なしで実行し、IDsの証拠を処理し、保存します。 --commit は、すべてのキューされた ID が成功した後にのみ実行します。失敗はチェックポイントが変更されていないままにします。 この例では、チャンネルごとに1つのディレクトリと1つのワーカーを使用します。

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

#### プラン → プロセス → コミット

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

- [資格情報のスケジュールと再利用](https://flashdata.dev/ja/docs/guides/recurring-tasks/reference.md)
- [動画の一覧を充実](https://flashdata.dev/ja/docs/guides/enrich-youtube-videos/reference.md)

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

### 新鮮なチャンネルチェックを意図的に開始

クエリヘルパーは、保存された応答を再利用します。 次のスケジュールチェックでは、新しい結果のファイル名を使用して、それを調べて、キューステップでchannel.jsonに完了した応答をコピーします。 processed-ids.json を動作させる。 最近のリストは、フルチャンネルのエクスポートやイベントストリームではありません。

#### 次へ チェック・ 新鮮なファイル名を選択してください

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

#### ステータス確認後、

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


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

## クエリを改善するための提案を使用する

提案は、ビデオレコードではなく結果[0]でフレーズを返す。 便利なフレーズを選択し、別のyoutube_searchリクエストを作成します。 あなたが研究している聴衆のための言語と領域を設定します。

### suggestions-request.json

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

### query.pyで一度に提出する

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


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

## 許可として扱うことなく、ライセンスラベルを保存

youtube_trainability は、動画のライセンスラベルを返します。許可: ["all"] は、クリエイティブ・コモンズのマップ、 ["none"] は、ライセンスメタデータが不足している部分もカバーします。 ビデオID、ソース応答、検索日時を保持します。 このラベルは、ダウンロード、再利用、トレーニングの権利を付与しません。

### license-request.json

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

### query.pyで一度に提出する

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


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

## アプリやエージェントの作業をバウンド

| ルール | 導入事例 |
| --- | --- |
| 充実する前に選ぶ | トピックタスク: 1 つの検索、選択したビデオのメタデータと 1 つの選択されたキャプション トラック。 アプリ内のコール予算を強制し、各ソースを別々に価格設定します。 |
| 実際の入力による再利用 | メタデータ:ビデオID +オプション。 注意: ビデオ ID + 言語 + トラック. チャンネルスナップショットは、検索時間や ID を実行する必要があります。 |
| 欠落した証拠を停止する | 空の発見結果を再試行しない、またはサイレントにキャプショントラックを切り替えないでください。 ユーザやワークフローが次のアクションを選択できるように、ギャップを返します。 |
| 利用状況の保存と失敗した作業 | 成功した応答での使用を保存します。 429 では、Retry-After を表彰します。不確実な投稿の後、別の有料クエリの前に History を確認してください。 |

- [Realtimeと非同期](https://flashdata.dev/ja/docs/reference/realtime-and-async/reference.md)
- [Batchとバルク](https://flashdata.dev/ja/docs/reference/batch-and-bulk/reference.md)
- [エラーとレトリー](https://flashdata.dev/ja/docs/errors/reference.md#retries)
- [現在の価格設定と残高](https://flashdata.dev/ja/docs/guides/credits-and-billing/reference.md)
