Cách lấy khóa API YouTube (API Dữ liệu YouTube v3) và gửi yêu cầu đầu tiên của bạn

Khoá API của YouTube là thông tin xác thực cho phép mã của bạn đọc dữ liệu công khai của YouTube: chi tiết video, số liệu thống kê kênh, kết quả tìm kiếm, nội dung danh sách phát. Tài liệu của Google nêu rõ: “Một yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi khoá API. Khoá này xác định dự án của bạn và cung cấp quyền truy cập API, hạn mức và báo cáo.” Không có khoá, không có dữ liệu.

Hướng dẫn này sẽ đưa bạn từ một dự án Google Cloud trống rỗng đến một yêu cầu hoạt động trong khoảng mười lăm phút. Bạn sẽ bật API Dữ liệu YouTube v3, tạo khoá, bảo mật nó, gọi API từ curl và Python, sau đó lưu khoá vào Apidog và lưu cuộc gọi dưới dạng một thử nghiệm có thể lặp lại. Nếu bạn muốn nắm bắt tổng quan trước, bài viết tổng quan về API Dữ liệu YouTube của chúng tôi sẽ đề cập đến những gì API cung cấp; bài đăng này là phần thực hành.

nút

Những gì bạn cần trước khi bắt đầu

Một tài khoản Google. Điều này đủ để mở Cloud Console và tạo dự án.
curl (đi kèm với macOS và hầu hết các bản phân phối Linux) và Python 3 với gói requests cho các mẫu mã.
Apidog nếu bạn muốn khoá được lưu trữ dưới dạng bí mật và yêu cầu được lưu dưới dạng thử nghiệm. Gói miễn phí bao gồm mọi thứ ở đây.

Bước 1: tạo dự án Google Cloud

Mở Google Cloud Console và đăng nhập. Sử dụng công cụ chọn dự án ở đầu trang để tạo một dự án mới, ví dụ youtube-integration. Mọi khoá API, nhóm hạn mức và báo cáo sử dụng mà bạn sẽ thấy sau này đều được giới hạn trong dự án này, vì vậy hãy giữ một dự án cho mỗi ứng dụng thay vì chia sẻ khoá giữa các công cụ không liên quan. Nếu ứng dụng đã có dự án, hãy sử dụng dự án đó.

Bước 2: bật API Dữ liệu YouTube v3

Các API thường tắt theo mặc định trong một dự án mới. Trong bảng điều khiển, hãy truy cập APIs & Dịch vụ, mở Thư viện API, tìm kiếm “YouTube Data API v3”, và bật nó. Hướng dẫn bắt đầu của Google mô tả cùng một kiểm tra từ hướng khác: truy cập trang Các API đã Bật và bật API nếu nó không được liệt kê.

Bỏ qua bước này và yêu cầu đầu tiên của bạn sẽ thất bại với lỗi 403 báo rằng API chưa được sử dụng trong dự án hoặc đã bị tắt. Đây là lý do phổ biến nhất khiến một khoá mới “không hoạt động”.

Bước 3: tạo khoá API

Đi tới APIs & Dịch vụ, sau đó chọn Thông tin xác thực. Nhấp vào Tạo thông tin xác thực và chọn khoá API. Bảng điều khiển sẽ tạo khoá ngay lập tức và hiển thị nó trong hộp thoại; sao chép nó đến một nơi an toàn.

Hãy coi khoá này như một mật khẩu. Đừng dán nó vào kho lưu trữ Git, luồng Slack hoặc gói JavaScript phía máy khách. Nếu nó đã lỡ xuất hiện trong một commit, hướng dẫn của chúng tôi về cách tìm và khắc phục các khoá API bị lộ sẽ hướng dẫn bạn cách xử lý.

Bước 4: hạn chế khoá

Tài liệu của Google nói rằng “Khoá API không bị hạn chế là không an toàn.” Ngay sau khi tạo, hãy nhấp vào Hạn chế khoá. Bạn có hai kiểm soát độc lập, được ghi lại trong hướng dẫn khoá API đám mây:

Hạn chế ứng dụng quyết định ai có thể trình bày khoá. Chọn một: trang web (tham chiếu HTTP, với hỗ trợ ký tự đại diện hạn chế), địa chỉ IP (IPv4, IPv6 hoặc dải CIDR), ứng dụng Android (tên gói cộng với dấu vân tay chứng chỉ SHA-1), hoặc ứng dụng iOS (ID gói). Một dịch vụ backend nên sử dụng địa chỉ IP. Một widget chỉ chạy trên trình duyệt nên sử dụng tham chiếu.
Hạn chế API quyết định API nào mà khoá có thể gọi. Chọn “Hạn chế khoá” và chỉ chọn YouTube Data API v3. Nếu khoá bị lộ, kẻ tấn công chỉ có được hạn mức YouTube và không gì khác.

Lưu và đợi một vài phút để thay đổi có hiệu lực trước khi bạn kiểm tra. Hai thói quen nữa từ cùng hướng dẫn: xoay vòng khoá định kỳ để hạn chế thiệt hại từ một khoá bị xâm phạm, và xóa các khoá cũ sau khi mọi người gọi đã chuyển sang khoá thay thế. Một lưu ý cho bước tiếp theo: nếu bạn hạn chế theo IP đến máy chủ của mình, curl từ máy tính xách tay của bạn sẽ bị chặn, vì vậy hãy kiểm tra từ máy chủ được phép hoặc tạo một khoá phát triển riêng.

Bước 5: thực hiện yêu cầu đầu tiên của bạn bằng curl và Python

Mọi điểm cuối đều nằm trong https://www.googleapis.com/youtube/v3/. Truyền khoá dưới dạng tham số truy vấn key, đó là cách các ví dụ của Google thực hiện, hoặc trong tiêu đề x-goog-api-key, giúp nó không xuất hiện trong URL và nhật ký truy cập. Cả hai cách đều hoạt động trên API trực tiếp.

Bắt đầu với videos.list, cuộc gọi hữu ích rẻ nhất: nó trả về chi tiết cho một hoặc nhiều ID video và tốn 1 đơn vị hạn mức. ID bên dưới là ID mà Google sử dụng trong tài liệu của họ.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

Một phản hồi được cắt gọn trông như thế này:

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

Tham số part là bắt buộc và kiểm soát các phần nào sẽ được trả về; snippet, statistics, contentDetails, và status là những phần bạn sẽ sử dụng nhiều nhất.

Bây giờ là một tìm kiếm, đây là cuộc gọi mà hầu hết mọi người đều muốn. Trong Python với requests:

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

Đối với search.list, part phải là snippet, maxResults mặc định là 5 và chấp nhận từ 0 đến 50, và type mặc định là video,channel,playlist, vì vậy hãy đặt nó thành video nếu bạn chỉ muốn video. Kết quả tìm kiếm mang videoId bên trong id, chứ không phải ở cấp cao nhất, đó là lý do tại sao vòng lặp trên đọc item["id"]["videoId"].

Bước 6: lưu trữ khoá và chạy yêu cầu trong Apidog

Một biến shell hoạt động cho một tập lệnh. Nó không hoạt động cho một nhóm, và nó không cung cấp cho bạn một kiểm tra đã lưu, có thể chạy lại. Đây là cùng một yêu cầu trong Apidog, với khoá được giữ ngoài đám mây.

Tạo một môi trường. Thêm một môi trường tên là YouTube với hai biến: base_url được đặt thành https://www.googleapis.com/youtube/v3, và youtube_api_key. Đối với khoá, hãy để giá trị chia sẻ dưới dạng trình giữ chỗ và dán khoá thật vào trường giá trị cục bộ. Các giá trị cục bộ vẫn nằm trong bộ nhớ cache của máy khách của bạn và không bao giờ đồng bộ hoá với đồng đội; thiết lập đầy đủ có trong hướng dẫn của chúng tôi về môi trường và biến bí mật trong Apidog.
Xây dựng yêu cầu. Yêu cầu mới, GET {{base_url}}/videos, tham số truy vấn part=snippet,statistics và id=7lCDEYXw3mM, và tiêu đề x-goog-api-key được đặt thành {{youtube_api_key}}. Chọn môi trường YouTube và gửi. Bạn sẽ thấy cùng một JSON như cuộc gọi curl.
Biến nó thành một bài kiểm tra. Trong trình xử lý hậu kỳ của yêu cầu, thêm các xác nhận: trạng thái bằng 200, và $.items[0].id bằng 7lCDEYXw3mM. Lưu yêu cầu và thêm nó vào một kịch bản kiểm tra. Kiểm tra giờ đây chạy theo yêu cầu, theo lịch trình, hoặc trong CI thông qua Apidog CLI, nơi --env-var "youtube_api_key=$YOUTUBE_API_KEY" chèn khoá tại thời điểm chạy thay vì lưu trữ nó.

Phần thưởng đến lần đầu tiên khoá được xoay vòng hoặc một hạn chế thay đổi: chạy lại một kịch bản và bạn sẽ biết trong vòng vài giây liệu mọi cuộc gọi YouTube vẫn hoạt động hay không. Tải Apidog để làm theo; nó miễn phí cho các nhóm lên đến bốn người.

Hạn mức và giới hạn

API Dữ liệu YouTube không tính phí bạn bằng đô la; nó tính phí bạn bằng đơn vị hạn mức, và các con số này đến từ trang tính toán hạn mức của Google. Mọi dự án bật API đều nhận được phân bổ mặc định này:

Nhóm	Mặc định mỗi ngày	Chi phí mỗi cuộc gọi
`search.list`	100 cuộc gọi	1 đơn vị (nhóm riêng)
`videos.insert`	100 cuộc gọi	1 đơn vị (nhóm riêng)
Tất cả các điểm cuối khác kết hợp	10.000 đơn vị	khác nhau, xem bên dưới

Trong nhóm chung 10.000 đơn vị, các phương thức liệt kê như videos.list, channels.list, playlistItems.list, và commentThreads.list có giá 1 đơn vị mỗi cái. Các thao tác ghi tốn nhiều hơn: videos.update và videos.delete là 50 đơn vị, và captions.insert là 400. Bốn quy tắc từ cùng trang định hình cách bạn nên thiết kế xung quanh điều này:

Hạn mức đặt lại vào lúc nửa đêm Giờ Thái Bình Dương.
Mọi yêu cầu, kể cả yêu cầu không hợp lệ, đều tốn ít nhất 1 đơn vị. Một vòng lặp thử lại cuộc gọi lỗi sẽ tiêu tốn hạn mức vô ích.
Mỗi trang bổ sung của kết quả phân trang có chi phí tương tự như trang đầu tiên.
Phân bổ mặc định “có thể thay đổi”. Kiểm tra trang, không phải hướng dẫn, trước khi bạn lập kế hoạch dung lượng.

Các hướng dẫn cũ hơn định giá một tìm kiếm là 100 đơn vị từ tổng số 10.000 đơn vị. Trang hiện tại đặt search.list vào nhóm riêng, vì vậy giới hạn vẫn là 100 tìm kiếm mỗi ngày, nhưng các tìm kiếm không còn ảnh hưởng đến hạn mức cho các cuộc gọi khác của bạn.

Nếu điều đó là chưa đủ, trang kiểm toán hạn mức và tuân thủ sẽ hướng bạn đến Biểu mẫu Yêu cầu Gia hạn Hạn mức và Kiểm toán Dịch vụ API YouTube. Trước khi bạn gửi, hãy lưu trữ các phản hồi, chỉ yêu cầu các giá trị part mà bạn cần, và nhóm các ID vào một cuộc gọi videos.list (tham số id chấp nhận một danh sách được phân tách bằng dấu phẩy). Mức sử dụng hiển thị trên trang Hạn mức trong Cloud Console.

Các lỗi thường gặp và cách khắc phục

Tài liệu tham khảo lỗi của Google liệt kê các mã lý do riêng của API. Hai dòng đầu tiên dưới đây đến từ việc gửi các yêu cầu thực tế đến API trực tiếp với khoá không hợp lệ và không có khoá.

HTTP	Lý do	Thông báo bạn sẽ thấy	Cách khắc phục
400	`badRequest` (`API_KEY_INVALID`)	“Khoá API không hợp lệ. Vui lòng cung cấp khoá API hợp lệ.”	Lỗi chính tả, khoá đã bị xoá, hoặc hạn chế API không bao gồm API Dữ liệu YouTube v3. Tạo lại hoặc chỉnh sửa khoá.
403	`forbidden`	“Phương thức không cho phép người gọi chưa đăng ký…”	Không có khoá nào được gửi. Thêm tham số `key` hoặc tiêu đề `x-goog-api-key`.
403	`quotaExceeded`	“Yêu cầu không thể hoàn thành vì bạn đã vượt quá hạn mức.”	Đợi đặt lại vào nửa đêm PT, cắt bỏ các cuộc gọi dư thừa, hoặc yêu cầu gia hạn.
400	`missingRequiredParameter`	“Yêu cầu thiếu một tham số bắt buộc.”	Hầu như luôn là thiếu `part`.
401	`authorizationRequired`	“Yêu cầu sử dụng tham số mine nhưng chưa được ủy quyền đúng cách.”	Cuộc gọi này cần mã thông báo OAuth 2.0, không phải khoá. Xem mục Câu hỏi thường gặp.

Thêm một kinh nghiệm thực tế: nếu một hạn chế ứng dụng không khớp với người gọi, bạn sẽ nhận được lỗi 403 nêu rõ tham chiếu hoặc IP bị chặn. Khắc phục hạn chế hoặc gọi từ máy chủ được phép. Và lưu ý rằng các luồng diễn đàn cũ hơn gọi lỗi khoá không hợp lệ là keyInvalid; API trực tiếp trả về badRequest với chi tiết API_KEY_INVALID, vì vậy hãy khớp theo thông báo hoặc chi tiết, không phải chuỗi lý do cũ.

Câu hỏi thường gặp

Khoá API YouTube có miễn phí không?

Có. Việc tạo khoá không tốn phí, và tài liệu định giá API bằng đơn vị hạn mức, không phải tiền. Phân bổ mặc định ở trên là những gì bạn nhận được mà không cần yêu cầu gì.

Khi nào tôi cần OAuth thay vì khoá API?

Khoá API xác định dự án của bạn và mở khóa dữ liệu công khai. Ngay khi bạn chạm vào dữ liệu người dùng riêng tư, hoặc chèn, cập nhật, hoặc xóa bất cứ điều gì, Google yêu cầu mã thông báo OAuth 2.0 từ người dùng sở hữu dữ liệu đó. Xếp hạng video, liệt kê các đăng ký của riêng bạn, hoặc sử dụng bộ lọc mine=true đều thuộc về phía OAuth. So sánh của chúng tôi về khoá API và mã thông báo bearer giải thích tại sao hai thông tin xác thực này trả lời các câu hỏi khác nhau.

Một tác nhân AI có thể sử dụng khoá API YouTube của tôi không?

Có, miễn là tác nhân chạy ở nơi mà các hạn chế của khoá cho phép. Một máy chủ YouTube MCP là một cách để chuyển dữ liệu video cho một trợ lý lập trình; hãy cấp cho nó một khoá chỉ giới hạn cho API Dữ liệu và cho máy mà nó chạy trên đó, và giữ nó khỏi chính lời nhắc.

Tôi nên làm gì nếu khoá bị lộ?

Xóa nó trong trang Thông tin xác thực và tạo một cái mới thay thế. Sau đó khắc phục nguồn gốc: chuyển khoá vào một giá trị cục bộ trong Apidog hoặc một kho lưu trữ bí mật, và quét kho lưu trữ để đảm bảo khoá cũ không còn nằm trong lịch sử.

Bước tiếp theo

Bây giờ bạn đã có một dự án, một API đã bật, một khoá bị hạn chế và một yêu cầu hoạt động từ curl, Python và Apidog. Nối kịch bản đã lưu vào CI và để trang Hạn mức cho bạn biết khi nào cần tối ưu hóa.