디스플레이 및 Video 360 API v2는 2024년 9월 3일에 지원 종료됩니다. 서비스가 중단되지 않도록 그 전에 v3로 마이그레이션하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

개요

구조화된 데이터 파일 (SDF)은 특수 형식의 쉼표로 구분된 값 (CSV)입니다. Display &Video 360 관련 데이터를 검색하고 업데이트하는 데 사용되는 동영상 360 리소스 되었습니다. 디스플레이를 통해 Video 360 API를 사용하면 맞춤 SDF를 생성 및 다운로드하고 이렇게 하면 Display &Video 360에서 정리되고 필터링된 데이터를 검색하고 동영상 360 리소스를 배포합니다

이 가이드에서는 SDF 다운로드 작업을 만들고 작업을 실행하고 결과 SDF를 다운로드합니다.

SDF 형식 및 버전 관리에 관한 정보는 SDF 참조 문서

할 일 만들기

SDF는 sdfdownloadtask라는 비동기 작업으로 생성됩니다. 이 작업을 만들 때 원하는 SDF와 관련된 매개변수를 정의합니다. 이 작업은 sdfdownloadtasks.create 메서드를 통해 진행됩니다. 이 다음 하위 섹션에서는 설정할 수 있는 매개변수에 대해 설명합니다.

버전 지정

구조화된 데이터 파일 형식은 디스플레이 및 새 버전과 이전 버전이 출시된 Video 360 API 정기적으로 지원 중단되었습니다. 따라서 항상 최신 버전의 SDF를 사용할 것을 권장합니다.

다음 메서드를 사용하여 원하는 SDF의 SDF 버전을 설정합니다. 요청 본문의 version 필드 설정하지 않거나 설정할 경우 SDF_VERSION_UNSPECIFIED로 전달하면 작업에서 기본 SDF 버전을 사용합니다. SDF 콘텐츠의 맥락으로 사용되는 광고주 또는 파트너 리소스입니다.

맥락 설정

사용 가능한 모든 리소스에 대한 데이터가 포함된 SDF를 생성할 수는 있지만 모든 개별 SDF는 단일 확인할 수 있습니다 이 컨텍스트는 요청 본문에서 partnerId 또는 advertiserId 필드 둘 중 정확히 하나 필드를 설정해야 합니다.

지정된 컨텍스트 내의 리소스만 결과 SDF에 포함됩니다. 지정된 파트너가 소유하지 않은 리소스를 기준으로 필터링하는 경우 해당 콘텐츠 또는 그 안의 콘텐츠가 모두 있습니다. 포함되지 않은 리소스로만 필터링할 경우 결과 파일은 은 비어 있습니다. 지정된 컨텍스트 외부의 리소스로 필터링 시도 오류를 반환하지 않으므로 컨텍스트가 올바른지 확인해야 합니다. 맞습니다.

적합한 필터 선택

위에서 설정한 컨텍스트 외에도 구조화된 데이터 파일을 생성할 수 있습니다. 포함하려는 특정 리소스 또는 리소스군을 지정할 수 있습니다

sdfdownloadtask에 사용할 수 있는 세 가지 필터가 있으며 각 필터는 특정 사양 유형을 사용합니다 한 번에 하나만 할당할 수 있습니다. sdfdownloadtask

ParentEntityFilter

ParentEntityFilter이(가) 사용 가능한 유형 중 가장 광범위한 값입니다. 필터를 적용합니다.

fileType 필드를 사용하면 원하는 작업에서 생성하려는 파일 형식을 선택합니다. 이것은 필수이며, 비워 두거나 FILE_TYPE_UNSPECIFIED로 설정하면 sdfdownloadtask이(가) 오류로 인해 완료됩니다.

filterType 및 filterIds 필드를 사용하여 검색 결과를 더 좁힐 수 있습니다. filterType는 리소스를 기준으로 필터링 기준 및 filterIds 고유 ID로 리소스를 식별합니다. 그 결과로 생성되는 SDF에 포함되는 항목은 다음과 같습니다. fileType에 의해 식별된 리소스 식별한 리소스의 하위 리소스 또는 filterType 및 filterIds.

IdFilter

IdFilter는 리소스만 포함하도록 요청을 필터링합니다. 있습니다.

IdFilter에는 인벤토리를 제외한 모든 SDF 유형에 대한 필드가 있습니다. 소스. 이러한 필드 각각은 생성된 SDF에 포함할 특정 리소스를 지정합니다. 제공된 ID 는 컨텍스트 집합 내에 있어야 하지만 직접적인 관련이 없어도 됩니다. 나 광고 항목을 요청하기 위해 특정 캠페인을 요청할 필요가 없습니다 반대의 경우도 마찬가지입니다. 생성된 파일 형식은 IdFilter에서 식별된 리소스에 해당합니다.

InventorySourceFilter

InventorySourceFilter에서는 필터링만 허용됩니다. 인벤토리 소스 리소스가 포함된 SDF의 경우 Google은 필터를 사용하여 인벤토리 소스 리소스에 관한 정보를 얻을 수 있습니다.

InventorySourceFilter에는 단수형이 있습니다. inventorySourceIds 필드로, 고유한 SDF에 포함할 인벤토리 소스 리소스의 ID입니다. 만약 inventorySourceIds에 제공된 목록이 비어 있습니다. 모두 설정된 컨텍스트에 있는 인벤토리 소스가 생성된 SDF에 포함됩니다.

요청하기

원하는 SDF의 매개변수를 파악했으면 요청을 구성할 수 있습니다. sdfdownloadtask를 만듭니다.

이 예시에서는 sdfdownloadtask ParentEntityFilter:

자바

// Create the filter structure
ParentEntityFilter parentEntityFilter = new ParentEntityFilter();
parentEntityFilter.setFileType(sdf-file-type-list);
parentEntityFilter.setFilterType(sdfFilterType);
parentEntityFilter.setFilterIds(filter-id-list);

// Configure the sdfdownloadtasks.create request
Sdfdownloadtasks.Create request =
   service
       .sdfdownloadtasks()
       .create(
           new CreateSdfDownloadTaskRequest()
               .setVersion(sdfVersion)
               .setAdvertiserId(advertiserId)
               .setParentEntityFilter(parentEntityFilter)
       );

// Create the sdfdownloadtask
Operation operationResponse = request.execute();

System.out.printf("Operation %s was created.\n",
   operationResponse.getName());

Python

# Configure the sdfdownloadtasks.create request
createSdfDownloadTaskRequest = {
    'version': sdf-version,
    'advertiserId': advertiser-id,
    'parentEntityFilter': {
        'fileType': sdf-file-type-list,
        'filterType': sdf-filter-type,
        'filterIds': filter-id-list
    }
}

# Create the sdfdownloadtask
operation = service.sdfdownloadtasks().create(
    body=createSdfDownloadTaskRequest).execute();

print("Operation %s was created." % operation["name"])

PHP

// Create the sdfdownloadtasks.create request structure
$createSdfDownloadTaskRequest =
    new Google_Service_DisplayVideo_CreateSdfDownloadTaskRequest();
$createSdfDownloadTaskRequest->setAdvertiserId(advertiser-id);
$createSdfDownloadTaskRequest->setVersion(sdf-version);

// Create and set the parent entity filter
$parentEntityFilter = new Google_Service_DisplayVideo_ParentEntityFilter();
$parentEntityFilter->setFileType(sdf-file-type-list);
$parentEntityFilter->setFilterType(sdf-filter-type);
if (!empty(filter-id-list)) {
    $parentEntityFilter->setFilterIds(filter-id-list);
}
$createSdfDownloadTaskRequest->setParentEntityFilter($parentEntityFilter);

// Call the API, creating the SDF Download Task.
$operation = $this->service->sdfdownloadtasks->create(
    $createSdfDownloadTaskRequest
);

printf('Operation %s was created.\n', $operation->getName());

요청 확인 및 다운로드 경로 가져오기

sdfdownloadtask 생성 시 작업 객체는 반환합니다. 이 작업은 비동기 SDF의 상태를 나타냅니다. 생성 작업에만 사용됩니다. 작업을 확인하여 sdfdownloadtasks.operations.get 메서드를 사용하여 지도 가장자리에 패딩을 추가할 수 있습니다.

완료되면 반환된 작업에 null이 아닌 값이 포함됩니다. done 필드 완료된 작업에는 다음 중 하나가 포함됩니다. response 또는 error 필드를 확인합니다. 있는 경우 error 필드에 오류 코드가 포함된 Status 객체 및 message: 현재 실행 중인 오류의 세부정보를 제공합니다. 수 있습니다. response 필드가 있으면 는 생성된 포드를 식별하는 resourceName 값을 가진 객체를 가지며 다운로드할 수 있습니다.

다음은 지수 백오프를 사용하여 요청을 확인하는 방법의 예입니다.

자바

String operationName = operationResponse.getName();

// Configure the Operations.get request
Sdfdownloadtasks.Operations.Get operationRequest =
   service
       .sdfdownloadtasks()
       .operations()
       .get(operationName);

// Configure exponential backoff for checking the status of our operation
ExponentialBackOff backOff = new ExponentialBackOff.Builder()
   .setInitialIntervalMillis(5000) // setting initial interval to five seconds
   .setMaxIntervalMillis(300000)  // setting max interval to five minutes
   .setMaxElapsedTimeMillis(18000000) // setting max elapsed time to five hours
   .build();

while (operationResponse.getDone() == null) {
 long backoffMillis = backOff.nextBackOffMillis();
 if (backoffMillis == ExponentialBackOff.STOP) {
   System.out.printf("The operation has taken more than five hours to
       complete.\n");
   return;
 }
 Thread.sleep(backoffMillis);

 // Get current status of operation
 operationResponse = operationRequest.execute();
}

// Check if the operation finished with an error and return
if (operationResponse.getError() != null) {
 System.out.printf("The operation finished in error with code %s: %s\n",
     operationResponse.getError().getCode(), operationResponse.getError()
         .getMessage());
 return;
}

System.out.printf(
    "The operation completed successfully. Resource %s was created.\n",
    operationResponse.getResponse().get("resourceName").toString());

Python

# The following values control retry behavior while
# the report is processing.
# Minimum amount of time between polling requests. Defaults to 5 seconds.
min_retry_interval = 5
# Maximum amount of time between polling requests. Defaults to 5 minutes.
max_retry_interval = 5 * 60
# Maximum amount of time to spend polling. Defaults to 5 hours.
max_retry_elapsed_time = 5 * 60 * 60

# Configure the Operations.get request
get_request = service.sdfdownloadtasks().operations().get(
  name=operation["name"]
)

sleep = 0
start_time = time.time()
while True:
  # Get current status of operation
  operation = get_request.execute()

  if "done" in operation:
    if "error" in operation:
      print("The operation finished in error with code %s: %s" % (
            operation["error"]["code"],
            operation["error"]["message"]))
    else:
      print("The operation completed successfully. Resource %s was created."
            % operation["response"]["resourceName"])
    break
  elif time.time() - start_time > max_retry_elapsed_time:
    print("Generation deadline exceeded.")

  sleep = next_sleep_interval(sleep)
  print("Operation still running, sleeping for %d seconds." % sleep)
  time.sleep(sleep)

def next_sleep_interval(previous_sleep_interval):
  """Calculates the next sleep interval based on the previous."""
  min_interval = previous_sleep_interval or min_retry_interval
  max_interval = previous_sleep_interval * 3 or min_retry_interval
  return min(max_retry_interval, random.randint(min_interval, max_interval))

PHP

// The following values control retry behavior
// while the task is processing.
// Minimum amount of time between polling requests. Defaults to 5 seconds.
$minRetryInterval = 5;
// Maximum amount of time between polling requests. Defaults to 5 minutes.
$maxRetryInterval = 300;
// Maximum amount of time to spend polling. Defaults to 5 hours.
$maxRetryElapsedTime = 18000;

$operationName = $operation->getName();

$sleepInterval = 0;
$startTime = time();

while (!$operation->getDone()) {
    if ($sleepInterval != 0) {
        printf(
            'The operation is still running, sleeping for %d seconds\n',
            $sleepInterval
        );
    }

    // Sleep before retrieving the SDF Download Task again.
    sleep($sleepInterval);

    // Call the API, retrieving the SDF Download Task.
    $operation = $this->service->sdfdownloadtasks_operations->get(
        $operation->getName()
    );

    // If the operation has exceeded the set deadline, throw an exception.
    if (time() - $startTime > $maxRetryElapsedTime) {
        printf('SDF download task processing deadline exceeded\n');
        throw new Exception(
            'Long-running operation processing deadline exceeded'
        );
    }

    // Generate the next sleep interval using exponential backoff logic.
    $sleepInterval = min(
        $maxRetryInterval,
        rand(
            max($minRetryInterval, $previousSleepInterval),
            max($minRetryInterval, $previousSleepInterval * 3)
        )
    );
}

// If the operation finished with an error, throw an exception.
if($operation->getError() !== null) {
    $error = $operation->getError();
    printf(
        'The operation finished in error with code %s: %s\n',
        $error->getCode(),
        $error->getMessage()
    );
    throw new Exception($error->getMessage());
}

// Print successfully generated resource.
$response = $operation->getResponse();
printf(
    'The operation completed successfully. Resource %s was '
        . 'created. Ready to download.\n',
    $response['resourceName']
);

파일 다운로드