Sử dụng DAI Ad Break API

DAI Ad Break API cho phép bạn tạo, quản lý thời gian và dữ liệu nhắm mục tiêu quảng cáo của các điểm chèn quảng cáo trong luồng phát trực tiếp.

Hướng dẫn này trình bày cách sử dụng DAI Ad Break API để tạo, cập nhật và xoá một điểm chèn quảng cáo cho sự kiện phát trực tiếp sử dụng tính năng Chèn quảng cáo động (DAI) của Google.

Điều kiện tiên quyết

Để sử dụng DAI Ad Break API, bạn cần có những điều kiện sau:

Thiết lập quyền truy cập API

Để bật API, hãy hoàn tất các bước sau:

  1. Tạo một tài khoản dịch vụ. Để biết thêm thông tin, hãy xem bài viết Tạo tài khoản dịch vụ.
  2. Thêm tài khoản dịch vụ vào mạng Google Ad Manager của bạn. Để biết thêm thông tin, hãy xem bài viết Thêm người dùng tài khoản dịch vụ để truy cập API.
  3. Cung cấp địa chỉ email tài khoản dịch vụ và mã mạng Google Ad Manager của bạn cho người quản lý tài khoản tại Google.
  4. Bật Google Ad Manager Video API trong dự án trên đám mây của bạn. Để biết thêm thông tin, hãy xem phần Bật "API và Dịch vụ" cho ứng dụng của bạn.

Xác thực bằng OAuth2

Để uỷ quyền cho các yêu cầu API, hãy làm theo các bước sau:

  1. Tạo mã truy cập bằng phạm vi https://www.googleapis.com/auth/video-ads.
  2. Trong mỗi yêu cầu, hãy thêm mã truy cập vào API dưới dạng giá trị tiêu đề HTTP Authorization Bearer. Để biết thêm thông tin, hãy xem phần Gọi API Google.

Ví dụ sau đây sẽ tạo mã thông báo OAuth bằng phạm vi của DAI Ad Break API:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

Nếu thành công, bạn sẽ thấy mã truy cập sau:

ya29.c.c0ASRK0GYUYU0...

Đưa ra yêu cầu đầu tiên

Để truy xuất các điểm chèn quảng cáo cho một sự kiện phát trực tiếp, hãy sử dụng phương thức GET để liệt kê tất cả các thực thể AdBreak theo khoá thành phần do hệ thống của sự kiện tạo hoặc khoá thành phần tuỳ chỉnh của bạn.

API Khoảng thời gian quảng cáo DAI chỉ trả về các thực thể AdBreak được tạo thông qua API, không bao gồm các khoảng thời gian quảng cáo được tạo từ tệp kê khai, yêu cầu phân đoạn nhóm hoặc yêu cầu tệp kê khai nhóm.

Yêu cầu ví dụ sau đây liệt kê các thực thể AdBreak theo giá trị assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

Nếu thành công, bạn sẽ thấy phản hồi JSON sau:

{
 "adBreaks": []
}

Khi tạo thêm các thực thể AdBreak thông qua API và yêu cầu danh sách, bạn sẽ thấy phản hồi JSON sau:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_SCHEDULED",
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_COMPLETE",
    },
    …
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Tạo thực thể AdBreak

Để thông báo cho DAI của Google về một khoảng thời gian chèn quảng cáo sắp tới cho một sự kiện phát trực tiếp, hãy sử dụng phương thức POST.

  • Để tạo một thực thể AdBreak mới, bạn phải đợi thực thể trước đó chuyển sang trạng thái BREAK_STATE_COMPLETE.
  • Ngoài ra, bạn có thể xoá thực thể AdBreak đang chờ xử lý để tạo một thực thể mới.
  • Để tạo nhiều thực thể AdBreak cho một sự kiện phát trực tiếp duy nhất, hãy liên hệ với người quản lý tài khoản để được thiết lập nâng cao.

Yêu cầu ví dụ sau đây tạo một điểm chèn quảng cáo dự kiến bắt đầu vào lúc 15:00:00 (giờ UTC) ngày 3 tháng 6 năm 2025:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/{NETWORK_CODE}/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

Nếu thành công, bạn sẽ thấy phản hồi JSON sau:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Kết quả này chứa mã nhận dạng điểm chèn quảng cáo cần thiết để truy xuất, sửa đổi hoặc xoá điểm chèn quảng cáo. Trong phản hồi mẫu, mã điểm chèn quảng cáo đã tạo là bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Truy xuất một thực thể AdBreak

Sử dụng phương thức GET để truy xuất thông tin chi tiết về một thực thể AdBreak cụ thể, bao gồm cả siêu dữ liệu về trạng thái và thời gian của điểm chèn quảng cáo.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Nếu thành công, bạn sẽ thấy phản hồi JSON sau:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Cập nhật thực thể AdBreak

Để sửa đổi một điểm chèn quảng cáo sắp tới trước khi quyết định quảng cáo bắt đầu, hãy sử dụng phương thức PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

Nếu thành công, bạn sẽ thấy phản hồi JSON sau:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Xoá thực thể AdBreak

Sử dụng phương thức DELETE để huỷ quyết định quảng cáo cho một điểm chèn quảng cáo được tạo thông qua API trước khi điểm chèn quảng cáo bắt đầu phân phát.

Yêu cầu ví dụ sau đây sẽ xoá một điểm chèn quảng cáo:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Nếu thành công, bạn sẽ thấy phản hồi HTTP/1.1 200 OK.

Tìm hiểu các tính năng nâng cao về thời điểm chèn quảng cáo

Sau khi tạo và quản lý các điểm chèn quảng cáo, hãy khám phá những tính năng sau của API Điểm chèn quảng cáo DAI: