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 cho các sự kiện (buổi phát sóng) và liên kết các sự kiện đó với luồng video (đại diện cho nội dung phát sóng thực tế).

API Phát trực tiếp thực sự 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 họ, trong khi YouTube Content ID API cho phép tương tác với hệ thống quản lý quyền của YouTube. Tuy nhiên, tất 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 dành cho những nhà phát triển muốn viết ứng dụng để tạo điều kiện 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à chính API này. Tài liệu này cũng cung cấp thông tin tổng quan về các hàm mà API hỗ trợ.

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

Buổi phát sóng

Buổi phát sóng đại diện cho một sự kiện mà bạn có thể xem trên YouTube khi sự kiện đó diễn ra. Bạn cũng có thể ghi lại và lưu các buổi phát sóng 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

Luồng phát xác định nội dung âm thanh và video đang được truyền đến YouTube. Mỗi buổi phát sóng được liên kết với một luồng video.

điểm chèn

cuepoint đại diện cho một điểm chèn quảng cáo mà bạn có thể chèn vào một buổi 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 của bạn:

• Lên lịch cho các buổi phát sóng và xác định chế độ cài đặt cho buổi 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 chế độ cài đặt cho buổi phát sóng, sau đó chọn chế độ cài đặt để áp dụng cho một buổi phát sóng cụ thể.

• Liên kết luồng video và buổi phát sóng.

• Cho phép người phát sóng xác định thông tin về một buổi phát sóng và video của buổi phát sóng đó (bằng YouTube Data API) cùng một lúc.

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

Trước khi bắt đầu

1. Bạn cần có Tài khoản Google để truy cập vào Google Cloud console, yêu cầu khoá API và đăng ký ứng dụng của mình.

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 Cloud 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 cho YouTube Data API v3 và nếu bạn là Đối tác nội dung của YouTube, hãy bật YouTube Content ID API.

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, độc lập về ngôn ngữ, cung cấp nội dung 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 cho các yêu cầu API

Như đã lưu ý ở trên, Live Streaming API sử dụng chức năng về mặt kỹ thuật là một phần của YouTube Data API hoặc YouTube Content ID API. 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 cho nội dung của mình. (Buổi phát sóng video trực tiếp là một ví dụ về nội dung.) 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 các yêu cầu về việc uỷ quyền cho các yêu cầu đối với Content ID API. Các yêu cầu này khác với các yêu cầu về việc uỷ quyền cho các yêu cầu khác của Live Streaming API.

Gọi Data API

Yêu cầu API phải được uỷ quyền bởi Tài khoản Google sở hữu kênh YouTube phát sóng.

Gọi Content ID API

Yêu cầu API phải được uỷ quyền bởi một Tài khoản Google được liên kết với chủ sở hữu nội dung sở hữu kênh YouTube 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 riêng biệt. Bảng dưới đây mô tả các loại tài nguyên mà bạn sẽ tương tác khi sử dụ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.

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

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

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

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

API cho phép và thực sự yêu cầu truy xuất tài nguyên một phầ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ớ 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 của 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 các 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:

• Yêu cầu 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.
• Yêu cầu này giúp 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 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 buổi 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à Đối tác nội dung của YouTube tham gia chương trình Content ID.

Quy trình xác nhận quyền sở hữu video phát sóng 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 yêu cầu 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à vòng đời của tài liệu 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 yêu cầu xác nhận quyền sở hữu.

Xem trước và kiểm thử nội dung của bạn

Sau khi nhận được luồng video đến, YouTube có thể phát video đó trên 2 luồng đi khác nhau:

• Luồng giám sát cho phép bạn xem trước (và kiểm thử) buổi phát sóng video của mình. Đây là một luồng riêng tư mà chỉ bạn mới có thể truy cập. Bạn chỉ có thể chuyển một buổi phát sóng sang giai đoạn testing nếu luồng giám sát của buổi phát sóng đó được 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 có thể xem. Bạn có thể đặt trạng thái quyền riêng tư của buổi phát sóng thành public, private hoặc unlisted. (Buổi phát sóng riêng tư chỉ những người dùng được mời xem mới có thể xem được, còn buổi phát sóng không công khai thì bất kỳ ai có đường liên kết để xem đều có thể xem được.)

  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 luồng phát sóng, bạn có thể kiểm soát thời gian chèn điểm chèn vào buổi phát sóng một cách chi tiết hơn.

  Tuy nhiên, việc trì hoãn luồng phát sóng sẽ khiến người thuyết trình trực tiếp khó tương tác với khán giả xem. Ngoài ra, việc trì hoãn buổi phát sóng sẽ làm tăng khả năng người xem khám phá các chi tiết chính về sự kiện từ các nguồn khác ngoài buổi 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, người xem có thể biết 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ự xem được trong buổi phát sóng.

YouTube khuyên bạn nên bật luồng giám sát cho buổi phát sóng để bạn có thể kiểm thử nội dung của mình. Bạn nên chọn có trì hoãn buổi phát sóng hay không dựa trên mong muốn kiểm soát thời gian của điểm chèn thay vì mong muốn tương tác với khán giả hoặc cung cấp thông tin theo thời gian thực về một sự kiện.

Chạy quảng cáo trong video trong luồng phát sóng

Trong một buổi phát sóng, bạn có thể chèn một cuepoint để cho biết rằng điểm chèn quảng cáo sẽ bắt đầu trong buổi phát sóng càng sớm càng tốt 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 buổi phát sóng.

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

1. Điểm chèn quảng cáo có thời lượng được xác định trước mà bạn đặt bằng thuộc tính cuepoint của tài nguyên durationSecs. Sau khi điểm chèn quảng cáo kết thúc, người xem sẽ quay lại buổi phát sóng trực tiếp.

2. Khi điểm chèn quảng cáo xuất hiện, quảng cáo chỉ phát trong trình phát video cho những người xem đang xem buổi phát sóng khi điểm chèn được chèn. Quảng cáo không chạy khi người xem làm mới trang nơi buổi phát sóng đang phát hoặc khi khách truy cập bắt đầu xem buổi phát sóng sau khi điểm chèn được chèn.

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

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

Khi chèn một điểm chèn, bạn có thể chỉ định rằng điểm chèn đó sẽ được chèn ngay lập tức hoặc nó sẽ được chèn vào một thời điểm cụ thể trong buổi 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 có bị trì hoãn hay không.

• Nếu luồng phát sóng của bạn không bị trì hoãn, thì bạn có thể chèn điểm chèn ngay lập tức hoặc sử 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à không chỉ định giá trị cho thuộc tính walltimeMs.

    Quan trọng: Xin lưu ý rằng người xem không thấy ngay nội dung quảng cáo kết quả. Có thể có độ trễ khoảng 30 giây trước khi người dùng thấy nội dung quảng cáo. Trong thời gian trễ đó, luồng phát sóng của bạn vẫn sẽ hiển thị với người xem và bạn cần xem luồng 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 của bạn.

  • Để 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 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.

• Nếu luồng phát sóng của bạn bị trì hoãn, thì bạn có thể chèn điểm chèn ngay lập tức như mô tả ở trên, chỉ định thời gian đồng hồ như mô tả ở trên hoặc bạn có thể 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 buổi phát sóng mà người xem sẽ thấy quảng cáo.

  Giá trị độ lệch được đo bằng mili giây kể từ khi bắt đầu luồng giám sát cho buổi phát sóng của bạn. Xin lưu ý rằng nếu buổi phát sóng của bạn có giai đoạn kiểm thử, thì luồng giám sát bắt đầu khi buổi phát sóng của bạn chuyển sang trạng thái testing Nếu không, luồng giám sát của bạn sẽ bắt đầu khi buổi phát sóng của bạn chuyển sang trạng thái live.

  Khi chèn một điểm chèn, 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ị độ lệch thời gian

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

Bạn có thể tính các giá trị có thể có cho thời gian độ lệch như sau:

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

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

• Một buổi phát sóng có giai đoạn kiểm thử 5 phút.
• Luồng phát sóng bị trì hoãn 60 giây sau luồng giám sát.
• Người phát sóng đang chèn điểm chèn 4 phút sau khi buổi phát sóng chuyển sang trạng thái live status. (Đây là 3 phút sau khi luồng phát sóng hiển thị.)

Trong trường hợp này, phạm vi thời gian độ lệch có thể có là [(485,000), (535,000)].

Các 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 được chín 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ì hoãn 60 giây hoặc 60000 mili giây.
• Δ=5000 – Vùng đệm 5 giây khi không thể chèn điểm chèn một cách đáng tin cậy.

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

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

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

  Nếu một buổi phát sóng bị kẹt ở trạng thái testStarting hoặc liveStarting, bạn cần gọi phương thức liveBroadcasts.delete và xoá buổi phát sóng đó. Sau đó, hãy tạo một buổi phát sóng mới, liên kết buổi phát sóng đó 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 thử.

  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 buổi phát sóng của bạn là active trước khi gọi phương thức đó.