Trang này được dịch bởi Cloud Translation API.

Tổng quan về API Phát trực tiếp trên YouTube

API Phát trực tiếp trên YouTube cho phép bạn tạo, cập nhật và quản lý các sự kiện trực tiếp trên YouTube. Khi sử dụng API này, bạn có thể lên lịch sự kiện (chương trình phát sóng) và liên kết sự kiện đó với luồng video đại diện cho nội dung phát sóng thực tế.

Live Streaming API (API Phát trực tiếp) bao gồm các thành phần của YouTube Data API và YouTube Content ID API. Data API cho phép người dùng YouTube quản lý tài khoản YouTube của mình, còn YouTube Content ID API cho phép các hoạt động tương tác với hệ thống quản lý quyền của YouTube. Tuy nhiên, tất cả các tài nguyên tạo nên Live Streaming API chỉ được dùng để tạo và quản lý các sự kiện trực tiếp.

Tài liệu này là dành cho những nhà phát triển muốn viết ứng dụng để hỗ trợ tính năng phát sóng trực tiếp trên YouTube. Hướng dẫn này giải thích các khái niệm cơ bản về YouTube và bản thân API. Trang này cũng cung cấp thông tin tổng quan về nhiều chức năng mà API hỗ trợ.

Các khái niệm chính

Buổi phát sóng: Bản phát sóng tượng trưng cho một sự kiện có thể xem trên YouTube khi sự kiện đó diễn ra. Video phát sóng cũng có thể được ghi lại và lưu dưới dạng video trên YouTube để người dùng có thể xem sau khi sự kiện diễn ra.
lượt phát trực tuyến: Một luồng xác định nội dung âm thanh-video sẽ được truyền đến YouTube. Mỗi chương trình phát sóng được liên kết với một luồng video.
điểm dừng: Điểm dừng biểu thị một điểm chèn quảng cáo có thể chèn vào chương trình phát sóng trực tiếp.

Các trường hợp sử dụng API

Danh sách dưới đây đề xuất một số cách để sử dụng API trong ứng dụng:

Lên lịch chương trình phát sóng và xác định chế độ cài đặt chương trình phát sóng. Ứng dụng của bạn có thể cho phép người dùng xác định trước các chế độ cài đặt truyền tin rồi chọn chế độ cài đặt đó để áp dụng cho một thông báo truyền tin cụ thể.
Liên kết luồng video và thông báo truyền phát.
Cho phép các đài phát sóng xác định thông tin về chương trình phát sóng và video của chương trình đó (sử dụng API dữ liệu của YouTube) cùng lúc.
Đơn giản hoá quá trình chuyển đổi giữa các trạng thái phát đi thông báo (testing, live, v.v.) và cho phép người dùng chèn điểm dừng.

Trước khi bắt đầu

Bạn cần có Tài khoản Google để truy cập Google API Console, yêu cầu khoá API và đăng ký ứng dụng của mình.
Đăng ký ứng dụng của bạn với Google để ứng dụng có thể gửi yêu cầu API.
Sau khi đăng ký ứng dụng, hãy chọn YouTube Data API làm một trong các dịch vụ mà ứng dụng của bạn sử dụng:
1. Chuyển đến API Console rồi chọn dự án mà bạn vừa đăng ký.
2. Truy cập vào trang API đã bật. Trong danh sách API, hãy đảm bảo trạng thái là BẬT đối với YouTube Data API v3 và nếu bạn là Đối tác nội dung YouTube, API YouTube Content ID đều có trạng thái.
Làm quen với các khái niệm chính của định dạng dữ liệu JSON (JavaScript Object Notation). JSON là một định dạng dữ liệu phổ biến, độc lập về ngôn ngữ, cung cấp bản trình bày văn bản đơn giản của các cấu trúc dữ liệu tuỳ ý. Để biết thêm thông tin, hãy xem json.org.

Uỷ quyền yêu cầu API

Như đã nêu ở trên, API Phát trực tiếp sử dụng chức năng thuộc về mặt kỹ thuật của API Dữ liệu YouTube hoặc API Content ID của YouTube. Bạn có thể sử dụng Content ID API để cung cấp cho YouTube siêu dữ liệu, thông tin về quyền sở hữu và thông tin về chính sách đối với tài sản của bạn. (Video phát sóng trực tiếp là một ví dụ về tài sản). API này cũng cho phép bạn xác nhận quyền sở hữu video và đặt chính sách quảng cáo cho video của mình.

Phần này giải thích yêu cầu uỷ quyền cho các yêu cầu đối với Content ID API, khác với các yêu cầu về việc uỷ quyền các yêu cầu Live Streaming API khác.

Đang gọi Data API: Yêu cầu API phải được Tài khoản Google sở hữu kênh YouTube phát sóng uỷ quyền.
Đang gọi Content ID API: Yêu cầu API phải được một Tài khoản Google liên kết với chủ sở hữu nội dung sở hữu kênh YouTube phát sóng uỷ quyền.

Tài nguyên và các loại tài nguyên

Tài nguyên là một thực thể dữ liệu riêng lẻ có một giá trị nhận dạng duy nhất. Bảng dưới đây mô tả các loại tài nguyên mà bạn sẽ tương tác bằng Live Streaming API. Về mặt kỹ thuật, tất cả các tài nguyên này thực sự được xác định là một phần của YouTube Data API hoặc YouTube Content ID API. Tuy nhiên, các tài nguyên liveBroadcast, liveStream và cuepoint chỉ được dùng để tạo và quản lý các sự kiện trực tiếp.

Tài nguyên
`liveBroadcast`	Chứa thông tin về sự kiện mà bạn đang phát sóng trên YouTube. Tài nguyên `liveBroadcast` là một phần mở rộng của tài nguyên video trên YouTube, đặt siêu dữ liệu của video chỉ liên quan đến một chương trình phát sóng trực tiếp chứ không phù hợp với các video khác trên YouTube. Do đó, tài nguyên `liveBroadcast` tương ứng với chính xác một tài nguyên video trên YouTube. Trên thực tế, tài nguyên `liveBroadcast` và tài nguyên `video` có cùng một mã nhận dạng. Sau khi tạo chương trình phát sóng bằng API Phát trực tiếp, bạn có thể sử dụng API dữ liệu YouTube để cung cấp siêu dữ liệu bổ sung về video đó.
`liveStream`	Chứa thông tin về luồng video mà bạn đang truyền đến YouTube. Sự kiện phát trực tiếp cung cấp nội dung sẽ được phát đến người dùng YouTube. Sau khi tạo, tài nguyên `liveStream` có thể được liên kết với chính xác một tài nguyên `liveBroadcast`. (Tương tự, tài nguyên `liveBroadcast` chỉ có thể liên kết với một tài nguyên `liveStream`.
`cuepoint`	Chèn một điểm dừng vào luồng video phát sóng, việc này có thể kích hoạt điểm chèn quảng cáo. Sử dụng phương thức `liveBroadcasts.cuepoint` để chèn điểm dừng trong quá trình phát sóng.
`video`	Đại diện cho một video trên YouTube. Như đã lưu ý ở trên, tài nguyên `liveBroadcast` là phần mở rộng của tài nguyên `video`. Bạn có thể sử dụng YouTube Data API để cập nhật siêu dữ liệu về video, chẳng hạn như vị trí ghi hình hoặc các khu vực có thể xem nội dung phát sóng.
`videoAdvertisingOptions`	Xác định chế độ cài đặt quảng cáo cho một video (hoặc chương trình phát sóng). Bạn sử dụng YouTube Content ID API để đặt các tuỳ chọn quảng cáo.
`asset`	Đại diện cho một phần tài sản trí tuệ, chẳng hạn như phim hoặc một tập của chương trình. Trong trường hợp này, video phát sóng là tài sản. Bạn sẽ dùng YouTube Content ID API để tạo và quản lý các tài nguyên của `asset`.
`claim`	Liên kết video với một tài sản mà video đó trùng khớp. Bạn tạo thông báo xác nhận quyền sở hữu bằng cách sử dụng YouTube Content ID API để xác định rằng bạn là chủ sở hữu của video phát sóng.
`policy`	Xác định các quy tắc nêu rõ các trường hợp mà bạn muốn nội dung của mình có thể xem được trên YouTube hoặc bị chặn không cho xuất hiện trên YouTube. Bạn cần áp dụng một chính sách cho video phát sóng và cũng có thể chỉ định chính sách mà YouTube sẽ áp dụng cho video do người dùng tải lên trùng khớp với video phát sóng của bạn.

Thao tác được hỗ trợ

Bảng sau đây trình bày các phương thức mà API hỗ trợ:

Hoạt động tính toán
`list`	Truy xuất (`GET`) một danh sách gồm 0 hoặc nhiều tài nguyên.
`insert`	Tạo (`POST`) một tài nguyên mới.
`update`	Sửa đổi (`PUT`) một tài nguyên hiện có để phản ánh dữ liệu trong yêu cầu của bạn.
`bind`	Liên kết tài nguyên `liveBroadcast` với tài nguyên `liveStream` hoặc xoá đường liên kết như vậy.
`transition`	Thay đổi trạng thái của tài nguyên `liveBroadcast` và bắt đầu mọi quy trình liên kết với trạng thái mới. Ví dụ: khi bạn chuyển đổi trạng thái của chương trình phát sóng sang `testing`, YouTube sẽ bắt đầu truyền video đến luồng giám sát của chương trình phát đó.
`delete`	Xoá (`DELETE`) một tài nguyên cụ thể.

Bảng dưới đây xác định các tác vụ được hỗ trợ cho các loại tài nguyên khác nhau. Các thao tác chèn, cập nhật hoặc xoá tài nguyên luôn yêu cầu sự cho phép của người dùng. Trong một số trường hợp, phương thức list hỗ trợ cả yêu cầu được uỷ quyền lẫn yêu cầu trái phép, trong đó các yêu cầu trái phép chỉ truy xuất dữ liệu công khai còn các yêu cầu được uỷ quyền cũng có thể truy xuất thông tin chỉ dành cho người dùng hiện đã xác thực.

Thao tác được hỗ trợ
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Tài nguyên một phần

API này cho phép và trên thực tế yêu cầu truy xuất một phần tài nguyên để các ứng dụng tránh chuyển, phân tích cú pháp và lưu trữ dữ liệu không cần thiết. Phương pháp này cũng đảm bảo API sử dụng tài nguyên mạng, CPU và bộ nhớ một cách hiệu quả hơn.

Tham số part là tham số bắt buộc đối với mọi yêu cầu API truy xuất hoặc trả về tài nguyên YouTube Data API. Tham số này xác định một hoặc nhiều thuộc tính tài nguyên cấp cao nhất (không lồng nhau) cần được đưa vào phản hồi API. Ví dụ: tài nguyên liveStream có các phần sau:

snippet
cdn
status

Tất cả các phần này đều là đối tượng chứa các thuộc tính lồng nhau và bạn có thể coi các đối tượng này là nhóm trường siêu dữ liệu mà máy chủ API có thể (hoặc không thể) truy xuất. Do đó, tham số part yêu cầu bạn chọn các thành phần tài nguyên mà ứng dụng của bạn thực sự sử dụng. Yêu cầu này phục vụ hai mục đích quan trọng:

Tính năng này giúp giảm độ trễ bằng cách ngăn máy chủ API dành thời gian truy xuất các trường siêu dữ liệu mà ứng dụng của bạn không sử dụng.
Tính năng này làm giảm việc sử dụng băng thông bằng cách giảm (hoặc loại bỏ) lượng dữ liệu không cần thiết mà ứng dụng của bạn có thể truy xuất.

Theo thời gian, khi tài nguyên bổ sung thêm phần, những lợi ích này sẽ chỉ tăng lên vì ứng dụng của bạn sẽ không yêu cầu các thuộc tính mới được giới thiệu mà ứng dụng không hỗ trợ.

Mẹo và phương pháp hay nhất

Xác nhận quyền sở hữu nội dung của bạn

Nếu muốn hiển thị quảng cáo trong khi phát sóng, bạn cần xác nhận quyền sở hữu video phát sóng trước khi sự kiện bắt đầu. Để xác nhận quyền sở hữu nội dung, bạn phải là một Đối tác nội dung của YouTube đang tham gia chương trình Content ID.

Quy trình xác nhận quyền sở hữu video phát trực tiếp khác với quy trình xác nhận quyền sở hữu video thông thường. Khi xác nhận quyền sở hữu video trực tiếp, bạn cần tạo thông báo xác nhận quyền sở hữu trước khi video thực sự tồn tại. API có hỗ trợ việc này và tài liệu về thời gian phát sóng giải thích các lệnh gọi YouTube Content ID API cho phép bạn tạo thông báo xác nhận quyền sở hữu.

Xem trước và kiểm tra nội dung

Khi nhận được luồng video đến của bạn, YouTube có thể phát video đó trên hai luồng đầu ra khác nhau:

Luồng theo dõi cho phép bạn xem trước (và kiểm tra) chương trình phát video của bạn. Đây là luồng riêng tư chỉ có bạn mới truy cập được. Bạn chỉ có thể chuyển đổi một thông báo truyền phát sang giai đoạn testing nếu luồng giám sát của thông báo đó được bật. Luồng giám sát không cho thấy điểm chèn quảng cáo.
Chương trình phát sóng là chương trình mà người xem của bạn có thể nhìn thấy. Bạn có thể đặt trạng thái quyền riêng tư của chương trình phát sóng là public, private hoặc unlisted. (Sự kiện phát sóng riêng tư chỉ hiển thị cho người dùng đã được mời xem sự kiện đó một cách rõ ràng, còn sự kiện phát sóng không công khai hiển thị với bất kỳ ai có liên kết để xem sự kiện đó).

Bạn có thể chọn trì hoãn luồng phát sóng để luồng này không chạy đồng thời với luồng giám sát. Bằng cách trì hoãn chương trình phát sóng, bạn có thể kiểm soát chi tiết hơn thời gian chèn điểm dừng vào chương trình phát sóng.

Tuy nhiên, việc trì hoãn chương trình phát sóng sẽ khiến người trình bày trực tiếp khó tương tác với khán giả xem. Ngoài ra, việc trì hoãn sự kiện phát sóng sẽ làm tăng khả năng người xem khám phá ra các thông tin chính về sự kiện từ những nguồn khác ngoài chương trình phát sóng của bạn. Ví dụ: nếu bạn đang phát sóng một sự kiện thể thao với độ trễ 60 giây, thì người xem có thể tìm hiểu về những khoảnh khắc quan trọng trong sự kiện đó từ các nguồn tin tức theo thời gian thực khác trước khi thực sự nhìn thấy những sự kiện đó trong chương trình phát sóng.

YouTube khuyên bạn nên bật chế độ giám sát sự kiện phát sóng để có thể kiểm tra nội dung của mình. Bạn cũng nên chọn xem có trì hoãn phát sóng hay không dựa trên mong muốn kiểm soát thời gian của các điểm dừng thay vì tương tác với khán giả hoặc đưa tin về một sự kiện theo thời gian thực.

Chạy quảng cáo trong video trong khi phát trực tiếp

Trong khi phát sóng, bạn có thể chèn một điểm dừng để cho biết rằng một điểm chèn quảng cáo sẽ bắt đầu trong sự kiện phát sóng ngay khi có thể hoặc vào một thời điểm cụ thể. Điểm chèn quảng cáo cho phép YouTube chạy quảng cáo trong video trong thời gian phát sóng.

Điểm chèn quảng cáo có các đặc điểm sau:

Tập hợp này có khoảng thời gian xác định trước. Bạn có thể đặt khoảng thời gian này bằng thuộc tính durationSecs của tài nguyên cuepoint. Sau khi điểm chèn quảng cáo kết thúc, người xem sẽ quay lại sự kiện phát sóng trực tiếp.
Khi có một điểm chèn quảng cáo, quảng cáo chỉ phát trong trình phát video cho những người xem đang xem chương trình phát sóng khi điểm dừng được chèn vào. Quảng cáo sẽ không chạy khi người xem làm mới trang đang phát chương trình phát sóng hoặc khi khách truy cập bắt đầu xem chương trình phát sóng sau khi chèn điểm dừng.

Trình tự các bước dưới đây phản ánh phương pháp hay nhất để chèn một điểm chèn quảng cáo trong chương trình phát sóng:

Đặt độ lệch thời gian

Khi chèn một điểm dừng, bạn có thể chỉ định rằng điểm dừng đó sẽ được chèn ngay lập tức hoặc nên được chèn vào một điểm cụ thể trong thông báo truyền tin. Các lựa chọn của bạn phụ thuộc vào việc video của bạn có bị trì hoãn hay không.

Nếu chương trình phát sóng của bạn không bị trì hoãn, bạn có thể chèn điểm dừng ngay lập tức hoặc dùng thuộc tính walltimeMs để điểm chèn quảng cáo bắt đầu vào một thời điểm cụ thể.
- Để bắt đầu điểm chèn quảng cáo ngay lập tức, hãy gọi phương thức liveBroadcasts.cuepoint. Trong tài nguyên trong nội dung yêu cầu, hãy đặt giá trị của thuộc tính insertionOffsetTimeMs thành 0 hoặc không chỉ định giá trị cho thuộc tính đó và đừng chỉ định giá trị cho thuộc tính walltimeMs.
  
  Lưu ý quan trọng: Xin lưu ý rằng người xem sẽ không thấy nội dung quảng cáo ngay lập tức. Nội dung quảng cáo có thể phải chờ khoảng 30 giây mới hiển thị cho người dùng. Trong khoảng thời gian trễ đó, người xem vẫn sẽ thấy sự kiện phát sóng của bạn. Bạn cần xem sự kiện phát trực tiếp đó để xác định thời điểm nội dung quảng cáo thực sự xuất hiện thay vì xuất hiện trong sự kiện phát trực tiếp giám sát.
- Để bắt đầu điểm chèn quảng cáo tại một thời điểm cụ thể, hãy gọi phương thức liveBroadcasts.cuepoint và sử dụng thuộc tính walltimeMs để chỉ định thời gian mong muốn. Giá trị thuộc tính là một số nguyên đại diện cho dấu thời gian bắt đầu của hệ thống.
Nếu sự kiện phát trực tiếp bị trì hoãn, bạn có thể chèn điểm dừng ngay như mô tả ở trên, chỉ định giờ theo đồng hồ như mô tả ở trên hoặc bạn có thể chỉ định một khoảng thời gian bù trừ để xác định thời điểm bắt đầu chèn quảng cáo. Mức chênh lệch thời gian chỉ định một thời điểm trong chương trình phát sóng của bạn khi người xem sẽ nhìn thấy quảng cáo.

Giá trị chênh lệch được tính bằng mili giây kể từ thời điểm bắt đầu luồng giám sát đối với tin truyền phát của bạn. Xin lưu ý rằng nếu chương trình phát sóng của bạn có giai đoạn thử nghiệm, thì luồng giám sát sẽ bắt đầu khi chương trình phát sóng chuyển sang trạng thái testing. Nếu không, sự kiện phát trực tiếp theo dõi của bạn sẽ bắt đầu khi thông báo truyền tin chuyển sang trạng thái live.

Khi chèn một điểm dừng, hãy đặt thuộc tính insertionOffsetTimeMs của tài nguyên cuepoint thành độ lệch mong muốn.

Tính giá trị chênh lệch thời gian

Để truy xuất giá trị chênh lệch, hãy gọi hàm getCurrentTime của API Trình phát YouTube cho trình phát đang phát luồng giám sát. Sử dụng giá trị được truy xuất để chèn điểm dừng vào luồng truyền phát tại thời điểm đó.

Có thể tính các giá trị thời gian bù trừ theo khoảng sau:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ là vùng đệm 5 giây ở đầu và cuối của các khoảng thời gian bù trừ có thể có khi YouTube không thể chèn chính xác điểm dừng. Ví dụ:

Một chương trình phát sóng có giai đoạn kiểm tra kéo dài 5 phút.
Luồng phát sóng bị trễ 60 giây sau luồng giám sát.
Đài phát sẽ chèn điểm dừng 4 phút sau khi nội dung truyền tin chuyển sang trạng thái live. (Đây là 3 phút sau khi luồng phát sóng hiển thị.)

Trong trường hợp này, khoảng thời gian bù trừ có thể là [(485,000), (535,000)].

Những thời gian này được chỉ định bằng mili giây và được tính bằng các giá trị sau:

elapsed_time=540000 – Luồng giám sát đã chạy trong 9 phút (540 giây, 540000 mili giây) khi phương thức liveBroadcasts.cuepoint được gọi.
broadcast_delay=60000 – Chương trình phát sóng bị trễ 60 giây hay 60.000 mili giây.
Δ=5000 – Vùng đệm 5 giây khi không thể chèn điểm dừng một cách chính xác.

Khắc phục sự cố và xử lý lỗi

Các nguyên tắc sau giải thích cách giải quyết các vấn đề cụ thể có thể phát sinh. Ngoài ra, hãy tham khảo tài liệu về lỗi để biết danh sách các lỗi mà mỗi phương thức API có thể trả về.

Khi một tin truyền chuyển đổi từ một trạng thái sang trạng thái khác, nó có thể tạm thời được gán một trạng thái khác trong khi YouTube hoàn tất các thao tác liên quan đến quá trình chuyển đổi đó. Ví dụ: Nếu bạn gửi yêu cầu liveBroadcasts.transition để thay đổi trạng thái của một chương trình phát sóng từ ready thành testing, thì YouTube sẽ đặt trạng thái của chương trình phát sóng thành testStarting rồi hoàn tất các hành động liên quan đến việc thay đổi trạng thái đó. Khi tất cả các thao tác đó đã hoàn tất, YouTube sẽ cập nhật trạng thái của chương trình phát sóng thành testing, qua đó cho biết rằng quá trình chuyển đổi đã hoàn tất.

Nếu một thông báo truyền tin bị kẹt với trạng thái testStarting hoặc liveStarting, bạn cần gọi phương thức liveBroadcasts.delete và xoá thông báo truyền tin đó. Sau đó, tạo một chương trình phát sóng mới, liên kết chương trình đó với chương trình phát trực tiếp của bạn rồi tiếp tục quy trình thử nghiệm.

Như đã lưu ý trong tài liệu về phương thức liveBroadcasts.transition, bạn nên xác nhận rằng giá trị của thuộc tính status.streamStatus cho luồng được liên kết với nội dung truyền tin là active trước khi gọi phương thức đó.