고객 일치 타겟팅 잠재고객 만들기

CreateUserListRequest를 전송하여 고객 매치 타겟팅 잠재고객을 만듭니다.

참고: 사용자 목록을 만들거나 업데이트하거나 삭제하는 작업은 EU 정치 광고 규정 (EU PAR) 정책을 준수해야 하며, 계정에 필요한 선언이 없는 경우 EU_POLITICAL_ADVERTISING_DECLARATION_REQUIRED 오류를 반환할 수 있습니다.

요청 본문 구성

UserList 리소스를 만듭니다. 다음은 설정할 일반적인 필드입니다.

displayName

필수 목록의 표시 이름입니다. 이름은 계정이 소유한 모든 목록 중에서 고유해야 합니다.

description

목록에 대한 간단한 설명입니다.

integrationCode

시스템의 ID입니다.

membershipDuration

잠재고객 구성원이 추가된 후 목록에 남아 있는 기간입니다. 값은 전체 일수에 해당해야 합니다. 설정하지 않으면 기본값은 최댓값입니다.

JSON을 사용하는 경우 기간 일수에 86400 (하루의 초 수)을 곱하여 초 수를 계산합니다. 그런 다음 값을 곱셈 결과로 설정하고 그 뒤에 s를 추가합니다. 예를 들어 포함 기간을 90일로 설정하려면 90 * 86400 = 7776000이므로 7776000s 값을 사용합니다.

프로토콜 버퍼 형식을 사용하는 경우 일수를 기반으로 Duration 객체를 구성하는 편의 메서드를 사용합니다(이러한 편의 메서드가 있는 경우). 예를 들어 Java용 protobuf-java-util 라이브러리에는 fromDays() 편의 메서드가 있습니다. 그렇지 않으면 기간 일수에 86400 (하루의 초 수)를 곱하여 초 수를 계산하고 결과를 사용하여 Duration 객체의 seconds 필드를 설정합니다.

고객 매치 타겟팅의 필수 입력란

고객 매치 타겟팅 잠재고객에는 ingestedUserListInfo 필드가 필요합니다.

다음은 잠재고객 구성원을 목록에 추가하는 데 사용할 데이터 유형에 따라 IngestedUserListInfo에 설정할 필드입니다.

연락처 정보 목록

연락처 정보 (해싱된 이메일 주소, 전화번호 또는 주소)를 사용하여 잠재고객 구성원을 정의하려면 다음 필드를 설정하세요.

uploadKeyTypes

CONTACT_ID 업로드 키 유형이 포함된 목록으로 설정합니다.

uploadKeyTypes 목록에는 항목이 하나만 포함되어야 합니다.

contactIdInfo

dataSourceType가 DataSourceType enum의 적절한 값으로 설정된 ContactIdInfo 메시지로 설정합니다.

Mobile ID 목록

모바일 ID를 사용하여 잠재고객 구성원을 정의하려면 다음 필드를 설정합니다.

uploadKeyTypes

MOBILE_ID 업로드 키 유형이 포함된 목록으로 설정합니다.

uploadKeyTypes 목록에는 항목이 하나만 포함되어야 합니다.

mobileIdInfo

MobileIdInfo 메시지로 설정합니다.

• dataSourceType를 DataSourceType enum의 적절한 값으로 설정합니다.

• keySpace을 IOS 또는 ANDROID로 설정합니다.

• appId를 데이터가 수집된 모바일 애플리케이션을 고유하게 식별하는 문자열로 설정합니다.

  • iOS의 경우 ID 문자열은 App Store URL 끝에 표시되는 9자리 문자열입니다. 예를 들어 App Store 링크가 https://apps.apple.com/us/app/flood-it/id476943146인 'Flood-It!' 앱의 경우 476943146입니다.

  • Android의 경우 ID 문자열은 애플리케이션의 패키지 이름입니다. 예를 들어 Google Play 링크가 https://play.google.com/store/apps/details?id=com.labpixies.flood인 'Flood-It!' 앱의 경우 com.labpixies.flood입니다.

사용자 ID 목록

사용자 ID를 사용하여 잠재고객 구성원을 정의하려면 다음 필드를 설정합니다.

uploadKeyTypes

USER_ID 업로드 키 유형이 포함된 목록으로 설정합니다.

uploadKeyTypes 목록에는 항목이 하나만 포함되어야 합니다.

요청 구성

고객 매치 타겟팅 잠재고객을 만들려면 UserList 리소스에 대한 create 요청을 구성합니다.

1. parent 필드를 계정의 리소스 이름으로 설정합니다. 리소스 이름은 accountTypes/{accountType}/accounts/{account} 형식을 따라야 합니다.

2. 요청 본문에 구성한 UserList를 사용합니다.

3. 사용자 인증 정보가 parent의 사용자인 Google 계정의 사용자 인증 정보가 아닌 경우 대상 및 헤더 구성에 설명된 대로 헤더를 설정합니다.

다음은 membershipDuration가 30일 (2592000s)인 고객 매치 타겟팅 잠재고객을 만드는 요청 샘플입니다. REST 탭을 선택하고 API 탐색기에서 열기를 클릭하여 브라우저에서 요청을 시도하거나 클라이언트 라이브러리를 설치한 경우 선택한 프로그래밍 언어의 탭을 선택합니다.

REST

연락처 정보

API 탐색기에서 열기

{
    "description": "Customer Match for contact info",
    "displayName": "Contact info audience",
    "ingestedUserListInfo": {
        "contactIdInfo": {
            "dataSourceType": "DATA_SOURCE_TYPE_FIRST_PARTY"
        },
        "uploadKeyTypes": [
            "CONTACT_ID"
        ]
    },
    "membershipDuration": "2592000s"
}

모바일 신분증

API 탐색기에서 열기

{
    "description": "Customer Match for mobile IDs",
    "displayName": "Mobile ID audience",
    "ingestedUserListInfo": {
        "mobileIdInfo": {
            "dataSourceType": "DATA_SOURCE_TYPE_FIRST_PARTY",
            "keySpace": "ANDROID",
            "appId": "com.labpixies.flood"
        },
        "uploadKeyTypes": [
            "MOBILE_ID"
        ]
    },
    "membershipDuration": "2592000s"
}

사용자 ID

API 탐색기에서 열기

{
    "description": "Customer Match for user IDs",
    "displayName": "User ID audience",
    "ingestedUserListInfo": {
        "userIdInfo": {
            "dataSourceType": "DATA_SOURCE_TYPE_FIRST_PARTY"
        },
        "uploadKeyTypes": [
            "USER_ID"
        ]
    },
    "membershipDuration": "2592000s"
}

.NET

// Runs the example.
private void RunExample(
    AccountType operatingAccountType,
    string operatingAccountId,
    bool validateOnly,
    UploadKeyType uploadKeyType = UploadKeyType.ContactId,
    AccountType? loginAccountType = null,
    string? loginAccountId = null,
    AccountType? linkedAccountType = null,
    string? linkedAccountId = null,
    KeySpace? keySpace = null,
    string? appId = null
)
{
    if (loginAccountId == null ^ loginAccountType == null)
    {
        throw new ArgumentException(
            "Must specify either both or neither of login account ID and login account "
                + "type"
        );
    }
    if (linkedAccountId == null ^ linkedAccountType == null)
    {
        throw new ArgumentException(
            "Must specify either both or neither of linked account ID and linked account "
                + "type"
        );
    }
    if (uploadKeyType == UploadKeyType.MobileId)
    {
        if (!keySpace.HasValue || string.IsNullOrEmpty(appId))
        {
            throw new ArgumentException(
                "Must specify both keySpace and appId when uploadKeyType is MobileId"
            );
        }
    }
    else if (keySpace.HasValue || !string.IsNullOrEmpty(appId))
    {
        throw new ArgumentException(
            "keySpace and appId are only supported when uploadKeyType is MobileId"
        );
    }

    // Optional: Sets headers to specify the login-account and linked-account if your
    // credentials aren't for a user in the operating account (for example, when
    // authenticating through a Google Ads manager account or Data Partner account).
    CallSettings? callSettings = null;
    if (loginAccountType.HasValue && loginAccountId != null)
    {
        callSettings = callSettings.WithHeader(
            "login-account",
            // Uses the AccountName utility to construct the login-account resource name.
            AccountName.Format(GetEnumOriginalName(loginAccountType.Value), loginAccountId)
        );
    }
    if (linkedAccountType.HasValue && linkedAccountId != null)
    {
        callSettings = callSettings.WithHeader(
            "linked-account",
            // Uses the AccountName utility to construct the linked-account resource name.
            AccountName.Format(
                GetEnumOriginalName(linkedAccountType.Value),
                linkedAccountId
            )
        );
    }

    // Configures the Customer Match user list.
    // For more details on constructing a UserList, see:
    // https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/create-audience
    var ingestedUserListInfo = new IngestedUserListInfo
    {
        // Sets to a list containing a single UploadKeyType.
        UploadKeyTypes = { uploadKeyType },
    };

    switch (uploadKeyType)
    {
        case UploadKeyType.ContactId:
            // Use CONTACT_ID for hashed email addresses, phone numbers, or physical
            // addresses.
            ingestedUserListInfo.ContactIdInfo = new ContactIdInfo
            {
                DataSourceType = DataSourceType.FirstParty,
            };
            break;
        case UploadKeyType.UserId:
            // Use USER_ID for first-party user IDs assigned to logged-in users.
            // Note: Display & Video 360 does not support USER_ID lists.
            ingestedUserListInfo.UserIdInfo = new UserIdInfo
            {
                DataSourceType = DataSourceType.FirstParty,
            };
            break;
        case UploadKeyType.MobileId:
            // Use MOBILE_ID for mobile advertising IDs.
            ingestedUserListInfo.MobileIdInfo = new MobileIdInfo
            {
                DataSourceType = DataSourceType.FirstParty,
                KeySpace = keySpace!.Value,
                AppId = appId,
            };
            break;
        default:
            throw new ArgumentException($"Unsupported upload key type: {uploadKeyType}");
    }

    string uploadKeyTypeName = GetEnumOriginalName(uploadKeyType);
    var userList = new UserList
    {
        // Required. The display name must be unique among all lists owned by the account.
        DisplayName =
            $"Customer Match ({uploadKeyTypeName}) - {DateTime.Now:yyyy-MM-dd HH:mm:ss}",
        Description = $"Customer Match audience for {uploadKeyTypeName}",
        // Optional. The duration an audience member remains in the list after being added.
        // Must correspond to whole days (defaults to maximum if not set).
        MembershipDuration = Duration.FromTimeSpan(TimeSpan.FromDays(30)),
        // Required for a Customer Match audience.
        IngestedUserListInfo = ingestedUserListInfo,
    };

    // Creates a client for UserListService.
    UserListServiceClient userListServiceClient = UserListServiceClient.Create();

    // Builds the request targeting the parent operating account.
    var request = new CreateUserListRequest
    {
        Parent = AccountName.Format(
            GetEnumOriginalName(operatingAccountType),
            operatingAccountId
        ),
        UserList = userList,
        // Sets validate_only. If true, then the Data Manager API only validates the
        // request but doesn't apply changes.
        ValidateOnly = validateOnly,
    };

    // Sends the request with any configured header settings.
    UserList response = userListServiceClient.CreateUserList(request, callSettings);

    // Logs the created user list. When validate_only is false, response.Id contains the
    // created user list ID, which you pass as the ProductDestinationId in subsequent
    // ingest or remove requests.
    Console.WriteLine($"Response:\n{response}");
}

// Returns the original proto enum name (for example, "GOOGLE_ADS" for
// AccountType.GoogleAds).
private static string GetEnumOriginalName<T>(T enumValue)
    where T : struct, System.Enum =>
    typeof(T)
        .GetField(enumValue.ToString())
        ?.GetCustomAttribute<OriginalNameAttribute>()
        ?.Name
    ?? enumValue.ToString();
CreateUserList.cs

자바

/**
 * Runs the example.
 *
 * @param params the parameters for the example
 * @throws IOException if the API request fails
 */
private void runExample(ParamsConfig params) throws IOException {
  // Optional: Sets headers to specify the login-account and linked-account if your credentials
  // aren't for a user in the operating account (for example, when authenticating through a Google
  // Ads manager account or Data Partner account).
  Map<String, String> headers = new HashMap<>();
  if (params.loginAccountId != null) {
    headers.put(
        "login-account",
        // Uses the AccountName utility to construct the login-account resource name.
        AccountName.format(params.loginAccountType.name(), params.loginAccountId));
  }
  if (params.linkedAccountId != null) {
    headers.put(
        "linked-account",
        // Uses the AccountName utility to construct the linked-account resource name.
        AccountName.format(params.linkedAccountType.name(), params.linkedAccountId));
  }

  // Configures the Customer Match user list.
  // For more details on constructing a UserList, see:
  // https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/create-audience
  IngestedUserListInfo.Builder ingestedUserListInfoBuilder =
      IngestedUserListInfo.newBuilder()
          // Sets to a single UploadKeyType.
          .addUploadKeyTypes(params.uploadKeyType);

  switch (params.uploadKeyType) {
    case CONTACT_ID:
      // Use CONTACT_ID for hashed email addresses, phone numbers, or physical addresses.
      ingestedUserListInfoBuilder.setContactIdInfo(
          ContactIdInfo.newBuilder()
              .setDataSourceType(DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY));
      break;
    case USER_ID:
      // Use USER_ID for first-party user IDs assigned to logged-in users.
      // Note: Display & Video 360 does not support USER_ID lists.
      ingestedUserListInfoBuilder.setUserIdInfo(
          UserIdInfo.newBuilder()
              .setDataSourceType(DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY));
      break;
    case MOBILE_ID:
      // Use MOBILE_ID for mobile advertising IDs.
      ingestedUserListInfoBuilder.setMobileIdInfo(
          MobileIdInfo.newBuilder()
              .setDataSourceType(DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY)
              .setKeySpace(params.keySpace)
              .setAppId(params.appId));
      break;
    default:
      throw new IllegalArgumentException(
          "Unsupported upload key type: " + params.uploadKeyType);
  }

  UserList userList =
      UserList.newBuilder()
          // Required. The display name must be unique among all lists owned by the account.
          .setDisplayName(
              String.format(
                  "Customer Match (%s) - %s",
                  params.uploadKeyType.name(),
                  LocalDateTime.now(ZoneId.systemDefault())
                      .format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))))
          .setDescription(
              String.format("Customer Match audience for %s", params.uploadKeyType.name()))
          // Optional. The duration an audience member remains in the list after being added. Must
          // correspond to whole days (defaults to maximum if not set).
          .setMembershipDuration(Durations.fromDays(30))
          // Required for a Customer Match audience.
          .setIngestedUserListInfo(ingestedUserListInfoBuilder)
          .build();

  // Configures the settings for UserListService to include headers.
  UserListServiceSettings userListServiceSettings =
      UserListServiceSettings.newBuilder()
          .setHeaderProvider(FixedHeaderProvider.create(headers))
          .build();

  // Creates a client for UserListService using the settings to include headers if provided.
  // Uses a try-with-resources block so the client shuts down properly.
  try (UserListServiceClient userListServiceClient =
      UserListServiceClient.create(userListServiceSettings)) {
    // Builds the request targeting the parent operating account.
    CreateUserListRequest request =
        CreateUserListRequest.newBuilder()
            .setParent(
                AccountName.format(params.operatingAccountType.name(), params.operatingAccountId))
            .setUserList(userList)
            // Sets validate_only. If true, then the Data Manager API only validates the request
            // but doesn't apply changes.
            .setValidateOnly(params.validateOnly)
            .build();

    // Sends the request.
    UserList response = userListServiceClient.createUserList(request);

    // Logs the created user list. When validate_only is false, response.getId() contains the
    // created user list ID, which you pass as the product_destination_id in subsequent ingest or
    // remove requests.
    LOGGER.info(() -> String.format("Response:%n%s", response));
  }
}
CreateUserList.java

노드

/**
 * Runs the CreateUserList sample.
 * @param {string} operatingAccountType The account type of the operating account.
 * @param {string} operatingAccountId The ID of the operating account.
 * @param {boolean} validateOnly Whether to enable validate_only on the request.
 * @param {protos.google.ads.datamanager.v1.IngestedUserListInfo.UploadKeyType} uploadKeyType The upload key type of the user list.
 * @param {string} [loginAccountType] The account type of the login account.
 * @param {string} [loginAccountId] The ID of the login account.
 * @param {string} [linkedAccountType] The account type of the linked account.
 * @param {string} [linkedAccountId] The ID of the linked account.
 * @param {protos.google.ads.datamanager.v1.MobileIdInfo.KeySpace} [keySpace] The key space of mobile IDs. Required when uploadKeyType is MOBILE_ID.
 * @param {string} [appId] The mobile application ID. Required when uploadKeyType is MOBILE_ID.
 */
async function runSample(
  operatingAccountType: string,
  operatingAccountId: string,
  validateOnly: boolean,
  uploadKeyType: protos.google.ads.datamanager.v1.IngestedUserListInfo.UploadKeyType = CONTACT_ID,
  loginAccountType?: string,
  loginAccountId?: string,
  linkedAccountType?: string,
  linkedAccountId?: string,
  keySpace?: protos.google.ads.datamanager.v1.MobileIdInfo.KeySpace,
  appId?: string,
) {
  // Creates a client for UserListService.
  const userListClient = new UserListServiceClient();

  // Optional: Sets headers to specify the login-account and linked-account if
  // your credentials aren't for a user in the operating account (for example,
  // when authenticating through a Google Ads manager account or Data Partner
  // account).
  const headers: {[key: string]: string} = {};

  if (loginAccountType && loginAccountId) {
    headers['login-account'] = userListClient.accountPath(
      loginAccountType,
      loginAccountId,
    );
  }

  if (linkedAccountType && linkedAccountId) {
    headers['linked-account'] = userListClient.accountPath(
      linkedAccountType,
      linkedAccountId,
    );
  }

  // Configures the Customer Match user list.
  // For more details on constructing a UserList, see:
  // https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/create-audience
  const ingestedUserListInfo = IngestedUserListInfo.create({
    // Sets to a list containing a single UploadKeyType.
    uploadKeyTypes: [uploadKeyType],
  });

  switch (uploadKeyType) {
    case CONTACT_ID:
      // Use CONTACT_ID for hashed email addresses, phone numbers, or physical
      // addresses.
      ingestedUserListInfo.contactIdInfo = ContactIdInfo.create({
        dataSourceType: DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY,
      });
      break;
    case USER_ID:
      // Use USER_ID for first-party user IDs assigned to logged-in users.
      // Note: Display & Video 360 does not support USER_ID lists.
      ingestedUserListInfo.userIdInfo = UserIdInfo.create({
        dataSourceType: DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY,
      });
      break;
    case MOBILE_ID:
      // Use MOBILE_ID for mobile advertising IDs.
      ingestedUserListInfo.mobileIdInfo = MobileIdInfo.create({
        dataSourceType: DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY,
        keySpace,
        appId,
      });
      break;
    default:
      throw new Error(`Unsupported upload key type: ${uploadKeyType}`);
  }

  const uploadKeyTypeName = Object.keys(
    IngestedUserListInfo.UploadKeyType,
  ).find(
    key =>
      IngestedUserListInfo.UploadKeyType[
        key as keyof typeof IngestedUserListInfo.UploadKeyType
      ] === uploadKeyType,
  );
  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);

  const userList = UserList.create({
    // Required. The display name must be unique among all lists owned by the
    // account.
    displayName: `Customer Match (${uploadKeyTypeName}) - ${timestamp}`,
    description: `Customer Match audience for ${uploadKeyTypeName}`,
    // Optional. The duration an audience member remains in the list after
    // being added. Must correspond to whole days (defaults to maximum if
    // not set).
    membershipDuration: Duration.create({
      seconds: 30 * 24 * 60 * 60,
    }),
    // Required for a Customer Match audience.
    ingestedUserListInfo,
  });

  // Builds the request targeting the parent operating account.
  const request = CreateUserListRequest.create({
    parent: userListClient.accountPath(
      operatingAccountType,
      operatingAccountId,
    ),
    userList,
    // Sets validate_only. If true, then the Data Manager API only
    // validates the request but doesn't apply changes.
    validateOnly,
  });

  // Sends the request with any configured header metadata.
  const [response] = await userListClient.createUserList(request, {
    otherArgs: {headers},
  });

  // Logs the created user list. When validate_only is false, response.id
  // contains the created user list ID, which you pass as the
  // product_destination_id in subsequent ingest or remove requests.
  console.log('Response:\n', response);
}
create_user_list.ts

PHP

/**
 * Runs the sample.
 *
 * @param int $operatingAccountType The account type of the operating account.
 * @param string $operatingAccountId The ID of the operating account.
 * @param bool $validateOnly Whether to enable validateOnly on the request.
 * @param int $uploadKeyType The upload key type of the user list.
 * @param int|null $loginAccountType The account type of the login account.
 * @param string|null $loginAccountId The ID of the login account.
 * @param int|null $linkedAccountType The account type of the linked account.
 * @param string|null $linkedAccountId The ID of the linked account.
 * @param int|null $keySpace The key space of mobile IDs. Required when uploadKeyType is MOBILE_ID.
 * @param string|null $appId The mobile application ID. Required when uploadKeyType is MOBILE_ID.
 */
function main(
    int $operatingAccountType,
    string $operatingAccountId,
    bool $validateOnly,
    int $uploadKeyType = UploadKeyType::CONTACT_ID,
    ?int $loginAccountType = null,
    ?string $loginAccountId = null,
    ?int $linkedAccountType = null,
    ?string $linkedAccountId = null,
    ?int $keySpace = null,
    ?string $appId = null
): void {
    // Validates parameters.
    if (($loginAccountType !== null) !== ($loginAccountId !== null)) {
        throw new \InvalidArgumentException(
            'Must specify either both or neither of login account type and login account ID'
        );
    }
    if (($linkedAccountType !== null) !== ($linkedAccountId !== null)) {
        throw new \InvalidArgumentException(
            'Must specify either both or neither of linked account type and linked account ID'
        );
    }
    if ($uploadKeyType === UploadKeyType::MOBILE_ID) {
        if ($keySpace === null || empty($appId)) {
            throw new \InvalidArgumentException(
                'Must specify both key_space and app_id when upload_key_type is MOBILE_ID'
            );
        }
    } elseif ($keySpace !== null || !empty($appId)) {
        throw new \InvalidArgumentException(
            'key_space and app_id are only supported when upload_key_type is MOBILE_ID'
        );
    }

    // Optional: Sets headers to specify the login-account and linked-account if
    // your credentials aren't for a user in the operating account (for example,
    // when authenticating through a Google Ads manager account or Data Partner
    // account).
    $headers = [];

    if ($loginAccountType !== null && $loginAccountId !== null) {
        $headers['login-account'] = [
            UserListServiceClient::accountName(
                AccountType::name($loginAccountType),
                $loginAccountId
            ),
        ];
    }

    if ($linkedAccountType !== null && $linkedAccountId !== null) {
        $headers['linked-account'] = [
            UserListServiceClient::accountName(
                AccountType::name($linkedAccountType),
                $linkedAccountId
            ),
        ];
    }

    // Configures the Customer Match user list.
    // For more details on constructing a UserList, see:
    // https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/create-audience
    $ingestedUserListInfo = (new IngestedUserListInfo())
        // Sets to a list containing a single UploadKeyType.
        ->setUploadKeyTypes([$uploadKeyType]);

    switch ($uploadKeyType) {
        case UploadKeyType::CONTACT_ID:
            // Use CONTACT_ID for hashed email addresses, phone numbers, or physical addresses.
            $ingestedUserListInfo->setContactIdInfo(
                (new ContactIdInfo())
                    ->setDataSourceType(DataSourceType::DATA_SOURCE_TYPE_FIRST_PARTY)
            );
            break;
        case UploadKeyType::USER_ID:
            // Use USER_ID for first-party user IDs assigned to logged-in users.
            // Note: Display & Video 360 does not support USER_ID lists.
            $ingestedUserListInfo->setUserIdInfo(
                (new UserIdInfo())
                    ->setDataSourceType(DataSourceType::DATA_SOURCE_TYPE_FIRST_PARTY)
            );
            break;
        case UploadKeyType::MOBILE_ID:
            // Use MOBILE_ID for mobile advertising IDs.
            $ingestedUserListInfo->setMobileIdInfo(
                (new MobileIdInfo())
                    ->setDataSourceType(DataSourceType::DATA_SOURCE_TYPE_FIRST_PARTY)
                    ->setKeySpace($keySpace)
                    ->setAppId($appId)
            );
            break;
        default:
            throw new \InvalidArgumentException(
                sprintf('Unsupported upload key type: %s', UploadKeyType::name($uploadKeyType))
            );
    }

    $uploadKeyTypeName = UploadKeyType::name($uploadKeyType);
    $userList = (new UserList())
        // Required. The display name must be unique among all lists owned by the account.
        ->setDisplayName(sprintf(
            'Customer Match (%s) - %s',
            $uploadKeyTypeName,
            (new \DateTime())->format('Y-m-d H:i:s')
        ))
        ->setDescription(sprintf('Customer Match audience for %s', $uploadKeyTypeName))
        // Optional. The duration an audience member remains in the list after being added. Must
        // correspond to whole days (defaults to maximum if not set).
        ->setMembershipDuration((new Duration())->setSeconds(30 * 24 * 60 * 60))
        // Required for a Customer Match audience.
        ->setIngestedUserListInfo($ingestedUserListInfo);

    // Creates a client for UserListService.
    $userListClient = new UserListServiceClient();

    // Builds the request targeting the parent operating account.
    $request = (new CreateUserListRequest())
        ->setParent(
            UserListServiceClient::accountName(
                AccountType::name($operatingAccountType),
                $operatingAccountId
            )
        )
        ->setUserList($userList)
        // Sets validate_only. If true, then the Data Manager API only validates the request
        // but doesn't apply changes.
        ->setValidateOnly($validateOnly);

    try {
        // Sends the request with any configured header metadata.
        $response = $userListClient->createUserList($request, ['headers' => $headers]);

        // Logs the created user list. When validate_only is false, $response->getId() contains the
        // created user list ID, which you pass as the product_destination_id in subsequent ingest or
        // remove requests.
        echo "Response:\n" . json_encode(json_decode($response->serializeToJsonString()), JSON_PRETTY_PRINT) . "\n";
    } catch (ApiException $e) {
        echo 'Error sending request: ' . $e->getMessage() . "\n";
    } finally {
        $userListClient->close();
    }
}
create_user_list.php

Python

def main(
    operating_account_type: datamanager_v1.ProductAccount.AccountType,
    operating_account_id: str,
    validate_only: bool,
    upload_key_type: datamanager_v1.IngestedUserListInfo.UploadKeyType = (
        datamanager_v1.IngestedUserListInfo.UploadKeyType.CONTACT_ID
    ),
    login_account_type: Optional[
        datamanager_v1.ProductAccount.AccountType
    ] = None,
    login_account_id: Optional[str] = None,
    linked_account_type: Optional[
        datamanager_v1.ProductAccount.AccountType
    ] = None,
    linked_account_id: Optional[str] = None,
    key_space: Optional[datamanager_v1.MobileIdInfo.KeySpace] = None,
    app_id: Optional[str] = None,
) -> None:
    """Runs the sample.

    Args:
     operating_account_type: the account type of the operating account.
     operating_account_id: the ID of the operating account.
     validate_only: whether to enable validate_only on the request.
     upload_key_type: the upload key type of the user list.
     login_account_type: the account type of the login account.
     login_account_id: the ID of the login account.
     linked_account_type: the account type of the linked account.
     linked_account_id: the ID of the linked account.
     key_space: the key space of mobile IDs. Required when upload_key_type is
       MOBILE_ID.
     app_id: the mobile application ID. Required when upload_key_type is
       MOBILE_ID.
    """

    # Validates parameters.
    if bool(login_account_type) != bool(login_account_id):
        raise ValueError(
            "Must specify either both or neither of login account type and "
            "login account ID"
        )
    if bool(linked_account_type) != bool(linked_account_id):
        raise ValueError(
            "Must specify either both or neither of linked account type and "
            "linked account ID"
        )
    if (
        upload_key_type
        == datamanager_v1.IngestedUserListInfo.UploadKeyType.MOBILE_ID
    ):
        if not key_space or not app_id:
            raise ValueError(
                "Must specify both key_space and app_id when upload_key_type "
                "is MOBILE_ID"
            )
    elif key_space or app_id:
        raise ValueError(
            "key_space and app_id are only supported when upload_key_type is "
            "MOBILE_ID"
        )

    # Optional: Sets headers to specify the login-account and linked-account if
    # your credentials aren't for a user in the operating account (for example,
    # when authenticating through a Google Ads manager account or Data Partner
    # account).
    headers = []

    if login_account_id:
        headers.append(
            (
                "login-account",
                f"accountTypes/{login_account_type.name}/accounts/{login_account_id}",
            )
        )

    if linked_account_id:
        headers.append(
            (
                "linked-account",
                f"accountTypes/{linked_account_type.name}/accounts/{linked_account_id}",
            )
        )

    # Configures the Customer Match user list.
    # For more details on constructing a UserList, see:
    # https://developers.google.com/data-manager/api/devguides/audiences/google-ads/customer-match/create-audience
    ingested_user_list_info = datamanager_v1.IngestedUserListInfo(
        # Sets to a list containing a single UploadKeyType.
        upload_key_types=[upload_key_type],
    )

    if (
        upload_key_type
        == datamanager_v1.IngestedUserListInfo.UploadKeyType.CONTACT_ID
    ):
        # Use CONTACT_ID for hashed email addresses, phone numbers, or physical
        # addresses.
        ingested_user_list_info.contact_id_info = datamanager_v1.ContactIdInfo(
            data_source_type=(
                datamanager_v1.DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY
            )
        )
    elif (
        upload_key_type
        == datamanager_v1.IngestedUserListInfo.UploadKeyType.USER_ID
    ):
        # Use USER_ID for first-party user IDs assigned to logged-in users.
        ingested_user_list_info.user_id_info = datamanager_v1.UserIdInfo(
            data_source_type=(
                datamanager_v1.DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY
            )
        )
    elif (
        upload_key_type
        == datamanager_v1.IngestedUserListInfo.UploadKeyType.MOBILE_ID
    ):
        # Use MOBILE_ID for mobile advertising IDs.
        ingested_user_list_info.mobile_id_info = datamanager_v1.MobileIdInfo(
            data_source_type=(
                datamanager_v1.DataSourceType.DATA_SOURCE_TYPE_FIRST_PARTY
            ),
            key_space=key_space,
            app_id=app_id,
        )
    else:
        raise ValueError(f"Unsupported upload key type: {upload_key_type}")

    user_list = datamanager_v1.UserList(
        # Required. The display name must be unique among all lists owned by the
        # account.
        display_name=(
            f"Customer Match ({upload_key_type.name}) - "
            f"{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
        ),
        description=f"Customer Match audience for {upload_key_type.name}",
        # Optional. The duration an audience member remains in the list after
        # being added. Must correspond to whole days (defaults to maximum if
        # not set).
        membership_duration=datetime.timedelta(days=30),
        # Required for a Customer Match audience.
        ingested_user_list_info=ingested_user_list_info,
    )

    # Creates a client for UserListService.
    user_list_client = datamanager_v1.UserListServiceClient()

    # Builds the request targeting the parent operating account.
    request = datamanager_v1.CreateUserListRequest(
        parent=f"accountTypes/{operating_account_type.name}/accounts/{operating_account_id}",
        user_list=user_list,
        # Sets validate_only. If true, then the Data Manager API only
        # validates the request but doesn't apply changes.
        validate_only=validate_only,
    )

    # Sends the request with any configured header metadata.
    response: datamanager_v1.UserList = user_list_client.create_user_list(
        request=request,
        metadata=headers,
    )

    # Logs the created user list. When validate_only is false, response.id
    # contains the created user list ID, which you pass as the
    # product_destination_id in subsequent ingest or remove requests.
    _logger.info("Response:\n%s", response)
create_user_list.py

요청 전송

요청을 전송하고 필요한 경우 login-account 또는 linked-account와 같은 요청 헤더를 포함합니다.

요청이 성공하면 응답에 출력 전용 id 및 name 필드가 채워진 생성된 UserList가 포함됩니다.

핵심사항: 생성된 UserList에서 반환된 id를 기록합니다. ingest, remove 또는 removeAll 요청에서 잠재고객 구성원을 업로드하거나 삭제할 때 이 id를 요청의 Destination에서 productDestinationId로 전달합니다.

요청이 실패하면 오류를 검사하여 실패 원인을 확인하고 요청 및 헤더를 업데이트하여 문제를 해결한 후 업데이트된 요청 및 헤더를 전송합니다.