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. Bằng cách sử dụng API, bạn có thể lên lịch sự kiện (chương trình phát sóng) và liên kết các sự kiện đó với luồng video thể hiện nội dung phát sóng thực tế.

Thực tế, API Phát trực tiếp bao gồm các thành phần của API Dữ liệu YouTube và API Content ID của YouTube. Data API cho phép người dùng YouTube quản lý tài khoản YouTube của họ, còn YouTube Content ID API cho phép người dù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 API phát trực tiếp chỉ được sử dụng để tạo và quản lý các sự kiện trực tiếp.

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

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

Buổi phát sóng
Một chương trình phát sóng biểu thị một sự kiện có thể xem trên YouTube ngay khi sự kiện đó diễn ra. Các chương trình 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 chúng diễn ra.
luồng
Một luồng xác định nội dung âm thanh kết hợp video đang đượ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
Một điểm dừng thể hiện 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 gợi ý một số cách để sử dụng API này trong ứng dụng của bạn:

  • Lên lịch phát sóng và xác định các chế độ cài đặt 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 cho nội dung phát sóng rồi chọn các chế độ cài đặt đó để áp dụng cho một chương trình phát sóng cụ thể.

  • Liên kết truyền phát và luồng video.

  • Cho phép đài phát xác định thông tin cùng lúc về chương trình phát sóng và video của chương trình đó (bằng API dữ liệu YouTube).

  • Đơn giản hoá quá trình chuyển đổi giữa các trạng thái truyền tin (ví dụ: testing hoặc live) và cho phép người dùng chèn điểm dừng.

Trước khi bắt đầu

  1. Bạn cần có một Tài khoản Google để truy cập vào Google API Console, yêu cầu khoá API và đăng ký ứng dụng.

  2. Đăng ký ứng dụng của bạn với Google để ứng dụng có thể gửi yêu cầu API.

  3. Sau khi đăng ký ứng dụng, hãy chọn YouTube Data API làm một trong những 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 của API YouTube Data API v3 là BẬT và API Content ID của YouTube (nếu bạn là Đối tác nội dung của YouTube).

  4. Làm quen với các khái niệm cốt lõi của định dạng dữ liệu JavaScript Object Notation (JSON). JSON là một định dạng dữ liệu phổ biến, không phụ thuộc vào 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.

Cho phép các yêu cầu API

Như đã lư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 YouTube Data API 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. (Một chương trình phát video trực tiếp là một ví dụ về một tài sản.) API này cũng giú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 các yêu cầu uỷ quyền đối với các yêu cầu gửi đến Content ID API. Yêu cầu này khác với yêu cầu uỷ quyền cho 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 đang phát sóng cấp phép.
Đang gọi Content ID API
Yêu cầu API phải được cho phép bởi 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 đang phát sóng.

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

Tài nguyên là một thực thể dữ liệu riêng lẻ có giá trị nhận dạng duy nhất. Bảng dưới đây mô tả các loại tài nguyên khác nhau mà bạn sẽ tương tác bằng cách sử dụng Live Streaming API. Về mặt kỹ thuật, tất cả các tài nguyên này đều 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, liveBroadcast, liveStream và cuepoint tài nguyên đang chỉ được dùng để tạo và quản lý 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. Đáp Tài nguyên liveBroadcast là một phần mở rộng của tài nguyên video trên YouTube và thiết lập video siêu dữ liệu liên quan đến chương trình phát sóng trực tiếp mà không liên quan đến 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ế, liveBroadcast và tài nguyên video sẽ chia sẻ 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 YouTube Data API để 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 này cung cấp nội dung sẽ được phát sóng cho người dùng YouTube. Sau khi được tạo, tài nguyên liveStream có thể được liên kết với đúng một tài nguyên liveBroadcast. (Tương tự, tài nguyên liveBroadcast chỉ có thể được 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, điểm này có thể kích hoạt điểm chèn quảng cáo. Sử dụng liveBroadcasts.cuepoint để chèn một điểm dừng trong khi 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 bản 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 lựa chọn quảng cáo.
asset Đại diện cho một 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ẽ sử dụng YouTube Content ID API để tạo và quản lý các tài nguyên 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 YouTube Content ID API để tự nhận mình là chủ sở hữu của video phát sóng.
policy Xác định các quy tắc chỉ định những 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 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 một chính sách mà YouTube sẽ áp dụng cho video do người dùng tải lên 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 này hỗ trợ:

Hoạt động tính toán
list Truy xuất (GET) một danh sách không có hoặc nhiều tài nguyên khác.
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 một tài nguyên liveBroadcast với một tài nguyên liveStream hoặc xoá một đườ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 bất kỳ quy trình nào được liên kết với trạng thái mới. Ví dụ: khi bạn chuyển 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 sóng đó.
delete Xoá (DELETE) một tài nguyên cụ thể.

Bảng dưới đây xác định các thao tác được hỗ trợ cho các loại tài nguyên khác nhau. Những 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 và yêu cầu trái phép, trong đó 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 đang được 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à thực sự 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 rằng API sử dụng tài nguyên mạng, CPU và bộ nhớ hiệu quả hơn.

Tham số part là tham số bắt buộc cho 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 những đối tượng này là các nhóm trường siêu dữ liệu mà máy chủ API có thể truy xuất (hoặc có thể không truy xuất). Do đó, tham số part sẽ yêu cầu bạn chọn các thành phần tài nguyên mà ứng dụng 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 làm 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 mứ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 được thêm nhiều phần hơ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 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à Đối tác nội dung của YouTube và 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 thông thường để xác nhận quyền sở hữu video. 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 này hỗ trợ việc này và tài liệu về vòng đời của một sự kiện truyền tin 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 thử nội dung

Sau 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 giám sát cho phép bạn xem trước (và kiểm tra) quá trình phát video của mình. Đây là luồng riêng tư chỉ bạn mới có thể truy cập. Bạn chỉ có thể chuyển thông báo truyền tin sang giai đoạn testing nếu luồng giám sát của thông báo truyền tin đó đang bật. Luồng giám sát không hiển thị điểm chèn quảng cáo.

  • Luồng phát sóng là luồng mà khán giả của bạn nhìn thấy. Bạn có thể thiết lập trạng thái quyền riêng tư của thông báo truyền tin thành public, private hoặc unlisted. (Chương trình phát sóng riêng tư chỉ hiển thị cho người dùng được mời xem rõ ràng, trong khi chương trình phát sóng không công khai chỉ hiển thị với bất kỳ ai có liên kết để xem chương trình phát sóng đó).

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

    Tuy nhiên, việc trì hoãn sự kiện phát sóng sẽ khiến người dẫn chương trình trực tiếp gặp khó khăn trong việc tương tác với khán giả xem nội dung. Ngoài ra, việc trì hoãn việc phát sóng sẽ làm tăng khả năng người xem khám phá các thông tin chi tiết chính về sự kiện từ các nguồn khác với nội dung phát sóng của bạn. Ví dụ: Nếu bạn phát sóng một sự kiện thể thao với độ trễ 60 giây, 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 chúng trong chương trình phát sóng.

YouTube khuyên bạn nên bật luồng giám sát cho chương trình phát sóng để có thể kiểm tra nội dung của mình. Đồng thời, bạn nên chọn việc hoãn phát sóng do muốn kiểm soát thời gian của các điểm dừng thay vì mong muốn 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 một sự kiện 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 điểm chèn quảng cáo sẽ bắt đầu sau nội dung phát càng sớm càng tốt hoặc vào 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 khi phát sóng.

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

  1. Khoảng thời gian này có thời lượng được xác định trước mà bạn đặt bằng cách sử dụngcuepoint durationSecs thuộc tính này. Sau khi điểm chèn quảng cáo kết thúc, người xem sẽ quay lại chương trình phát sóng trực tiếp.

  2. Khi một điểm chèn quảng cáo xảy ra, một quảng cáo chỉ phát trong trình phát video đối với những người đang xem video thông báo truyền tin khi chèn điểm dừng. Quảng cáo không chạy khi người xem làm mới trang nơi chương trình phát sóng đang phát hoặc khi khách truy cập bắt đầu xem chương trình phát sóng sau đã 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 khi phát sóng:

Đặt chênh lệch thời gian

Khi chèn một điểm dừng, bạn có thể chỉ định rằng nó nên được chèn ngay lập tức hoặc nó phải được chèn tại một điểm cụ thể trong chương trình phát sóng. Các lựa chọn của bạn phụ thuộc vào việc luồng phát sóng cho video của bạn bị trễ.

  • Nếu luồng 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 sử dụng 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 trong nội dung yêu cầu, đặt giá trị Thuộc tính insertionOffsetTimeMs thành 0 hoặc không chỉ định giá trị cho thuộc tính đó và không chỉ định một giá trị cho walltimeMs thuộc tính này.

      Lưu ý quan trọng: Xin lưu ý rằng người xem sẽ không nhìn thấy quảng cáo sau đó ngay lập tức. Có thể có sự chậm trễ khoảng 30 giây trước khi nội dung quảng cáo được hiển thị cho người dùng. Trong thời gian trì hoãn đó, bạn vẫn có thể xem được luồng phát sóng của mình người xem và bạn cần phải xem chương trình phát sóng để xác định thời điểm nội dung quảng cáo thực sự hiển thị thay vì luồng giám sát.

    • Để bắt đầu điểm chèn quảng cáo vào một thời điểm cụ thể, hãy gọi liveBroadcasts.cuepoint và sử dụng phương thức walltimeMs để chỉ định thời gian mong muốn. Giá trị thuộc tính là một số nguyên biểu thị dấu thời gian bắt đầu của hệ thống.

  • Nếu luồng phát sóng của bạn bị trễ, bạn có thể chèn điểm dừng ngay lập tức như được mô tả ở trên, chỉ định giờ đồng hồ như được mô tả ở trên hoặc bạn có thể chỉ định chênh lệch thời gian để xác định thời điểm điểm chèn quảng cáo sẽ bắt đầu. Độ lệch thời gian chỉ định một thời điểm trong chương trình phát sóng thời điểm người xem nên nhìn thấy quảng cáo.

    Giá trị bù trừ được tính bằng mili giây kể từ thời điểm bắt đầu luồng giám sát cho nội dung phát sóng 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 bắt đầu khi chương trình phát sóng chuyển đổi sang trạng thái testing. Nếu không, luồng giám sát bắt đầu khi sự kiện phát sóng chuyển đổi sang trạng thái live.

    Khi chèn một điểm dừng, hãy đặt giá trị của tài nguyên cuepoint insertionOffsetTimeMs với độ lệch mong muốn.

Tính giá trị bù trừ thời gian

Để truy xuất giá trị độ 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 màn hình. Sử dụng giá trị được truy xuất để chèn điểm dừng vào luồng phát sóng tại thời điểm đó.

Các giá trị có thể có cho thời gian bù trừ có thể được tính như phạm vi sau:

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

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

  • Chương trình phát sóng có giai đoạn thử nghiệm 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 đang chèn điểm dừng sau 4 phút chuyển đổi sang Trạng thái live. (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 theo 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 – Luồng 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 đáng tin cậy.

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

Các hướng dẫn sau đây giải thích cách giải quyết các vấn đề cụ thể có thể phát sinh. Đối với danh sách về lỗi mà mỗi phương thức API có thể trả về, hãy xem bài viết API Phát trực tiếp trên YouTube – Lỗi.

  • Khi một chương trình phát sóng chuyển đổi từ trạng thái này sang trạng thái khác, chương trình đó có thể tạm thời được chỉ định trạng thái khác trong khi YouTube hoàn tất các hành động liên kết với 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 chương trình phát sóng từ ready thành testing, YouTube sẽ đặt trạng thái của chương trình phát sóng thành testStarting, sau đó hoàn tất các thao tác 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, do đó cho biết quá trình chuyển đổi đã hoàn tất.

    Nếu thông báo truyền tin gặp sự cố 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, ràng buộc chương trình đó với sự kiện phát trực tiếp của bạn và tiếp tục quy trình kiểm tra.

    Như đã nê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 liên kết với thông báo truyền tin là active trước khi gọi phương thức đó.