# YouTube Data Thực hành tốt nhất

Tìm đoạn phim thích hợp, chọn các đường dẫn phụ đề và xử lý các kênh mới tải lên mà không lặp lại công việc.

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/guides/youtube-data-guide
Xem lại: 2026-11-04 by FlashData

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

## Hãy bắt đầu với những thông tin bạn đã có

Mỗi nguồn đều trả lời một câu hỏi khác nhau. Bỏ qua phát hiện cho một video đã biết ID hoặc điều khiển kênh, và làm giàu chỉ những video mà nhiệm vụ của bạn cần.

| Nhiệm vụ của anh | Nguồn | Quyết định |
| --- | --- | --- |
| Tìm đoạn phim về một chủ đề | youtube_search | Bắt đầu với năm ứng cử viên, sau đó chọn bằng sự liên quan. |
| Xem xét một video đã biết | youtube_metadata | Lấy tiêu đề, kênh, thời gian và chú thích ngôn ngữ. |
| Tóm tắt hoặc trích dẫn những gì đã được nói | youtube_transcript / youtube_captions | Chọn một ngôn ngữ và một đường dẫn tự động hoặc thủ công. |
| Kiểm tra các kênh được tải lên gần đây | youtube_channel | So sánh đã trở lại IDs với tiến trình của bạn IDs. |

- [Tìm đoạn phim](https://flashdata.dev/vi/docs/guides/youtube-data-guide/reference.md#discover)
- [Làm việc với một video đã biết](https://flashdata.dev/vi/docs/guides/youtube-data-guide/reference.md#metadata)
- [Theo dõi kênh](https://flashdata.dev/vi/docs/guides/youtube-data-guide/reference.md#channel)

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

## Chạy các ví dụ yêu cầu

Lưu mỗi JSON cơ thể sử dụng tên tập tin được hiển thị. Python sử dụng query.py Trợ giúp bên dưới; cURL có thể đệ trình cùng một tập tin. Dùng chìa khóa có quyền truy cập mã nguồn và tín dụng sẵn sàng. Mỗi người nộp là một yêu cầu, bất kể số lượng các video trả lời.

### Python

Python 3.10+. Cài đặt yêu cầu một lần, lưu query.py Bên dưới, hãy dùng lệnh bên cạnh mỗi yêu cầu. Đang sử dụng lại kết xuất đã có; thay đổi dữ liệu nhập cần thiết tên tập tin xuất mới.

#### Cài đặt

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


### cURL

Bash. Thay thế REQUEST.json và RESULT.json với tên tập tin cho ví dụ đã chọn của bạn. Kiểm tra kết quả trước khi lặp lại một yêu cầu; lệnh này lưu HTTP Cơ thể thậm chí là một lỗi lầm.

#### Gửi một người được cứu JSON yêu cầu

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

### Đặt khóa API

Dùng lại FLASHDATA_API_KEY từ thiết bị cuối hoặc cửa hàng bí mật. Nếu không, hãy nhập phím, dùng dấu nhắc ẩn bên dưới. Hãy giữ nó trong quá trình chạy những ví dụ này.

#### Bash

##### Đặt phím

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

##### Đặt phím

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


- [Phím API](https://flashdata.dev/app/api-keys)
- [Dùng thử tác nhân và liên kết tài khoản](https://flashdata.dev/vi/docs/guides/agent-onboarding/reference.md)

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

### Lưu query.py cho Python Ví dụ

Tạo query.py trong một thư mục làm việc mới và sao chép toàn bộ mã bên dưới vào đó. Lưu yêu cầu JSON tập tin và các tập tin khác Python Văn lệnh trong thư mục này, và chạy mọi lệnh từ đó.

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

## Tìm ứng cử viên trước khi lấy chi tiết

Bộ lọc video loại bỏ các loại kết quả khác; phụ đề thu hẹp phát hiện vào video với phụ đề. Nó không chọn ngôn ngữ chú thích hoặc bảo đảm theo dõi bạn cần. Lưu dạng discover-request.json.

### discover-request.json

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

### Gửi một lần với query.py

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


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

### Chọn bằng cách liên quan, không phải thứ nhất ID

Lưu candidates.py bên cạnh query.py và search.jsonSau đó chạy nó từ tập tài liệu đó. Nó giữ thứ tự tìm kiếm và gỡ bỏ bản sao video IDs. Kiểm tra tựa đề, kênh và khoảng thời gian, rồi sao chép một tác vụ đã chọn ID trong yêu cầu tiếp theo. Danh sách rỗng là một tìm kiếm hoàn tất mà không có ứng cử viên nào.

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

#### Đọc việc tìm kiếm đã lưu

```bash
python candidates.py
```


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

### Mở rộng chỉ khi danh sách ngắn không đủ

Hỗ trợ tìm kiếm chuẩn max_results lên đến 20. Cho một bộ sưu tập rộng hơn, chuyển sang youtube_search_extendedhỗ trợ để 700 và có giá cả riêng biệt. Ví dụ này hỏi 50; kiểm tra xem kết quả đầu tiên của bạn có hữu ích trước khi làm phong phú tất cả chúng không.

#### extended-request.json

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

#### Chạy một lần

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

- [Đưa ra một cuộc tìm kiếm dài hơn một cách tùy tiện](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#async)
- [Enrich đã chọn IDs](https://flashdata.dev/vi/docs/guides/enrich-youtube-videos/reference.md)

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

## Chỉ lấy siêu dữ liệu mà tính năng bạn cần

Thay mẫu video_id với phần chọn của bạn ID. Giữ các định dạng và chương bị tắt cho một thẻ video đơn giản hoặc kiểm tra chú thích. Bật include_chapters cho một đường nét, hay include_formats khi chọn định dạng phương tiện.

### metadata-request.json

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

### Gửi một lần với query.py

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

- [Trường phản ứng siêu dữ liệu](https://flashdata.dev/vi/docs/sources/youtube_metadata/reference.md#response)
- [Dịch vụ giao hàng phương tiện](https://flashdata.dev/vi/docs/guides/media-delivery-pipeline/reference.md)

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

### Xem xét các ngôn ngữ sẵn sàng

Đọc results[0].transcriptLanguages trước khi chọn phụ đề. Định dạng, chương và ngôn ngữ là trường trên đối tượng video trả về; kỷ lục sử dụng thuộc về phản ứng bên ngoài.

| Thiết lập | Dùng nó đi |
| --- | --- |
| language | Một mã từ transcriptLanguages, như en hoặc zh-Hans. Danh sách này không phân biệt dấu vết thủ công và tự động. |
| auto: true | Một dấu vết tự động tạo ra. |
| auto: false | Một đường dẫn được cấp bằng tay đã có. Không có hậu thuẫn giữa hai loại đường đua. |

#### Đọc metadata.json và không truy vấn

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


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

## Chọn ngôn ngữ và theo dõi một cách rõ ràng

Dùng cùng một cách video_id là yêu cầu siêu dữ liệu của bạn, thay đổi ngôn ngữ và tự động để khớp với dấu vết đã chọn. youtube_transcript mặc định auto: true; youtube_captions mặc định auto: false. Cả hai đều lấy phụ đề đã có, không phải từ ngữ.

### captions-request.json

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

### Gửi một lần với query.py

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

- [Tham số](https://flashdata.dev/vi/docs/sources/youtube_transcript/reference.md#parameters)
- [Hoàn tất tóm tắt](https://flashdata.dev/vi/docs/guides/youtube-summary/reference.md)

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

### Giữ lại thời gian với bằng chứng

Lưu cite-segments.py bên cạnh captions.json và chạy nó từ tập tài liệu đó. Dùng results[0].segments Đối với trích dẫn: bắt đầu và kết thúc là giây. Bảo tồn languageCode và isAutoGenerated với đoạn văn. fullText là hữu ích cho việc đọc, nhưng không thay thế thời gian đoạn. Nếu đường ray đã được chọn bị mất, hãy ghi lại khoảng trống trước khi quyết định xem có một yêu cầu nào đáng giá không.

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

#### Đọc ghi chú thích hoặc không API cuộc gọi

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


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

## Tiến hành chỉ video mới từ kênh đã biết

Dùng tay cầm và giới hạn của kênh video_limit (1–100). results[0].videos là danh sách mới nhất; videoCount là siêu dữ liệu kênh, chứ không phải số mục đã trả về. Hãy chọn một giới hạn và thời khóa biểu bao gồm việc tải lên bạn cần quan sát.

### channel-request.json

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

### Gửi một lần với query.py

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


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

### Giữ hàng đợi và kiểm tra hoàn tất

Lưu channel-queue.py bên cạnh query.py và channel.jsonvà lấy nó từ tập tài liệu đó. Chạy không có đối số cần tạo new-ids.jsonSau đó tiến hành và lưu trữ bằng chứng cho những người IDs. Chạy --commit Chỉ sau mỗi lần xếp hàng ID Thành công; thất bại khiến điểm kiểm soát không thay đổi. Dùng một thư mục trên mỗi kênh và một công nhân cho ví dụ này.

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

#### lên kế hoạch

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

- [Thời gian biểu và cách sử dụng lại](https://flashdata.dev/vi/docs/guides/recurring-tasks/reference.md)
- [Làm giàu danh sách các video](https://flashdata.dev/vi/docs/guides/enrich-youtube-videos/reference.md)

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

### Bắt đầu kiểm tra kênh mới một cách có chủ tâm

Trợ giúp truy vấn tái sử dụng một phản ứng đã lưu. Đối với kiểm tra kế hoạch tiếp, sử dụng một tên tập tin kết quả mới, thanh tra nó, sau đó sao chép mà hoàn tất phản ứng channel.json để xếp hàng bước. Giữ processed-ids.json giữa các điểm chạy. Danh sách gần đây không phải là xuất khẩu toàn bộ hay một luồng sự kiện.

#### Kiểm tra kế tiếp · chọn tên tập tin mới

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

#### Sau khi xác nhận trạng thái đã được thực hiện

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


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

## Dùng gợi ý để cải thiện truy vấn

Đề nghị trả lại đoạn văn trong results[0]Không phải ghi hình. Chọn một đoạn văn hữu ích và tạo một đoạn riêng youtube_search yêu cầu. Thiết lập ngôn ngữ và khu vực cho khán giả mà bạn đang nghiên cứu.

### suggestions-request.json

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

### Gửi một lần với query.py

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


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

## Lưu nhãn chứng nhận vào đó mà không xem chúng là quyền hạn

youtube_trainability trả lại nhãn chứng nhận cho một video. Cho phép: ["all"] Bản đồ đến sáng tạo chung; ["none"] Cũng bao gồm cả siêu dữ liệu bản quyền bị mất. Giữ đoạn video ID, phản hồi từ nguồn và ngày tái thu hồi. Nhãn này không cung cấp quyền tải về, sử dụng lại hoặc đào tạo.

### license-request.json

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

### Gửi một lần với query.py

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


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

## Hạn chế công việc cho ứng dụng và tác nhân

| Quy tắc | Thi hành |
| --- | --- |
| Chọn trước khi làm giàu | Đối với một nhiệm vụ chủ đề: một tìm kiếm, một trong những được chọn của video siêu dữ liệu và một theo dõi chú thích. Đặt ngân sách cuộc gọi trong ứng dụng của bạn, và giá mỗi nguồn riêng biệt. |
| Dùng lại bởi đầu vào thật | Siêu dữ liệu: ID + tùy chọn. Độ xoay: ID + ngôn ngữ + theo dõi. Chụp ảnh kênh cũng cần thời gian phục hồi hoặc chạy ID. |
| Dừng lại khi thiếu bằng chứng | Đừng thử lại một kết quả phát hiện rỗng hoặc chuyển đổi dấu vết tiêu đề âm thầm. Trả lại khoảng trống để người dùng hoặc dòng làm việc có thể chọn hành động tiếp theo. |
| Bảo tồn sử dụng và làm việc thất bại | Lưu sử dụng với các đáp ứng thành công. Vào 429danh dự Retry-After; sau khi không chắc chắn phục tùng, kiểm tra History trước khi có một truy vấn trả tiền khác. |

- [Realtime và mộtsync](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md)
- [Batch và diện tích](https://flashdata.dev/vi/docs/reference/batch-and-bulk/reference.md)
- [Lỗi và nhắc lại](https://flashdata.dev/vi/docs/errors/reference.md#retries)
- [Giá trị và số dư hiện tại](https://flashdata.dev/vi/docs/guides/credits-and-billing/reference.md)
