DAI 광고 시점 API 사용

DAI 광고 시점 API를 사용하면 라이브 스트림의 광고 시점의 타이밍과 광고 타겟팅 데이터를 만들고 관리할 수 있습니다.

이 가이드에서는 DAI 광고 시점 API를 사용하여 Google 동적 광고 삽입 (DAI) 라이브 스트림 이벤트의 광고 시점을 만들고 업데이트하고 삭제하는 방법을 설명합니다.

기본 요건

DAI 광고 시점 API를 사용하려면 다음이 필요합니다.

  • admanagervideo.googleapis.com 서비스가 사용 설정된 Google Cloud 프로젝트 자세한 내용은 Cloud 프로젝트 만들기를 참고하세요.
  • Google DAI 라이브 스트림 이벤트가 있는 Google Ad Manager 네트워크 자세한 내용은 DAI용 라이브 스트림 설정을 참고하세요.

API 액세스 설정

API를 사용 설정하려면 다음 단계를 완료하세요.

  1. 서비스 계정을 만듭니다. 자세한 내용은 서비스 계정 만들기를 참고하세요.
  2. Google Ad Manager 네트워크에 서비스 계정을 추가합니다. 자세한 내용은 API 액세스에 서비스 계정 사용자 추가를 참고하세요.
  3. Google 계정 관리자에게 서비스 계정 이메일 주소와 Google Ad Manager 네트워크 코드를 제공합니다.
  4. Google Cloud 프로젝트에서 Google Ad Manager Video API를 사용 설정합니다. 자세한 내용은 앱에 'API 및 서비스' 사용 설정을 참고하세요.

OAuth2로 인증

API 요청을 승인하려면 다음 단계를 따르세요.

  1. https://www.googleapis.com/auth/video-ads 범위로 액세스 토큰을 생성합니다.
  2. 각 요청에서 API에 대한 액세스 토큰을 Authorization HTTP 헤더 Bearer 값으로 포함합니다. 자세한 내용은 Google API 호출을 참고하세요.

다음 예에서는 DAI 광고 시점 API의 범위로 OAuth 토큰을 생성합니다.

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

성공하면 다음과 같은 액세스 토큰이 표시됩니다.

ya29.c.c0ASRK0GYUYU0...

첫 번째 요청하기

라이브 스트림 이벤트의 광고 시점을 가져오려면 GET 메서드를 사용하여 이벤트의 시스템 생성 애셋 키 또는 맞춤 애셋 키로 모든 AdBreak 항목을 나열합니다.

DAI 광고 시점 API는 API를 통해 생성된 AdBreak 항목만 반환하며, 매니페스트, 광고 모음 세그먼트 요청 또는 광고 모음 매니페스트 요청에서 생성된 광고 시점은 제외됩니다.

다음 예시 요청은 assetKey 값으로 AdBreak 항목을 나열합니다.

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"

성공하면 다음과 같은 JSON 응답이 표시됩니다.

{
 "adBreaks": []
}

API를 통해 AdBreak 항목을 추가로 만들고 목록을 요청하면 다음 JSON 응답이 표시됩니다.

{
 "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"
}

AdBreak 엔티티 만들기

라이브 스트림 이벤트의 예정된 광고 시점을 Google DAI에 알리려면 POST 메서드를 사용하세요.

  • 새 AdBreak 항목을 만들려면 이전 항목이 BREAK_STATE_COMPLETE 상태로 전환될 때까지 기다려야 합니다.
  • 또는 새 AdBreak 항목을 만들기 위해 대기 중인 항목을 삭제할 수 있습니다.
  • 단일 라이브 스트림 이벤트에 대해 두 개 이상의 AdBreak 항목을 만들려면 계정 관리자에게 문의하여 고급 구성을 요청하세요.

다음 예시 요청은 2025년 6월 3일 15:00:00(UTC)에 시작될 것으로 예상되는 광고 시점을 만듭니다.

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"
  }'

성공하면 다음과 같은 JSON 응답이 표시됩니다.

{
  "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",
}

결과에는 광고 시점을 가져오거나 수정하거나 삭제하는 데 필요한 광고 시점 ID가 포함됩니다. 응답 예시에서 생성된 광고 시점 ID는 bcc402a6-9880-4b8b-8e4a-a8cd3688f854입니다.

AdBreak 항목 가져오기

GET 메서드를 사용하여 광고 시점 상태 및 타이밍 메타데이터를 비롯한 특정 AdBreak 항목의 세부정보를 가져옵니다.

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'

성공하면 다음과 같은 JSON 응답이 표시됩니다.

{
  "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",
}

AdBreak 항목 업데이트

광고 결정이 시작되기 전에 예정된 광고 시점을 수정하려면 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"}'

성공하면 다음과 같은 JSON 응답이 표시됩니다.

{
  "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",
}

광고 시점 항목 삭제

광고 시점이 게재되기 전에 API를 통해 생성된 광고 시점의 광고 결정을 취소하려면 DELETE 메서드를 사용하세요.

다음 예시 요청은 광고 시점을 삭제합니다.

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

성공하면 HTTP/1.1 200 OK 응답이 표시됩니다.

고급 광고 시간 기능 알아보기

광고 시점을 만들고 관리한 후 DAI 광고 시점 API의 다음 기능을 살펴보세요.