Creare un segmento di pubblico Customer Match

Crea un segmento di pubblico Customer Match inviando una richiesta CreateUserListRequest.

Nota: le operazioni che creano, aggiornano o eliminano gli elenchi di utenti devono essere conformi alle norme del Regolamento relativo agli annunci politici nell'UE (EU PAR) e possono restituire un errore EU_POLITICAL_ADVERTISING_DECLARATION_REQUIRED se l'account non dispone della dichiarazione richiesta.

Crea il corpo della richiesta

Crea una risorsa UserList. Ecco i campi comuni da impostare.

displayName

Obbligatorio Il nome visualizzato dell'elenco. Il nome deve essere univoco tra tutti gli elenchi di proprietà dell'account.

description

Una breve descrizione dell'elenco.

integrationCode

Un ID del tuo sistema.

membershipDuration

La durata della permanenza di un membro del segmento di pubblico nell'elenco dopo l'aggiunta. Il valore deve corrispondere a giorni interi. Se non viene impostato, il valore predefinito è il massimo.

Se utilizzi JSON, calcola il numero di secondi moltiplicando i giorni di durata per 86400 (il numero di secondi al giorno). Poi imposta il valore sul risultato della moltiplicazione, seguito da s. Ad esempio, se vuoi una durata inclusione di 90 giorni, utilizza il valore 7776000s, poiché 90 * 86400 = 7776000.

Se utilizzi il formato buffer di protocollo, utilizza il metodo di convenienza per creare un oggetto Duration in base al numero di giorni, se esiste un metodo di convenienza di questo tipo. Ad esempio, la libreria protobuf-java-util per Java ha un metodo di utilità fromDays(). In caso contrario, calcola il numero di secondi moltiplicando i giorni di durata per 86400 (il numero di secondi al giorno) e utilizza il risultato per impostare il campo seconds dell'oggetto Duration.

Campi obbligatori per Customer Match

Il campo ingestedUserListInfo è obbligatorio per un segmento di pubblico Customer Match.

Di seguito sono riportati i campi da impostare in IngestedUserListInfo in base al tipo di dati che vuoi utilizzare per aggiungere membri del segmento di pubblico all'elenco.

Elenco dei dati di contatto

Imposta i seguenti campi se vuoi utilizzare i dati di contatto (indirizzi email, numeri di telefono o indirizzi sottoposti ad hashing) per definire i membri del segmento di pubblico:

uploadKeyTypes

Imposta un elenco contenente il tipo di chiave di caricamento CONTACT_ID.

L'elenco uploadKeyTypes deve contenere una sola voce.

contactIdInfo

Imposta su un messaggio ContactIdInfo con dataSourceType impostato sul valore appropriato dell'enum DataSourceType.

Elenco di identità digitali

Imposta i seguenti campi se vuoi utilizzare le identità digitali per definire i membri del segmento di pubblico:

uploadKeyTypes

Imposta un elenco contenente il tipo di chiave di caricamento MOBILE_ID.

L'elenco uploadKeyTypes deve contenere una sola voce.

mobileIdInfo

Imposta su un messaggio MobileIdInfo:

• Imposta dataSourceType sul valore appropriato dell'enum DataSourceType.

• Imposta keySpace su IOS o ANDROID.

• Imposta appId sulla stringa che identifica in modo univoco l'applicazione mobile da cui sono stati raccolti i dati.

  • Per iOS, la stringa ID è la stringa di 9 cifre che appare alla fine dell'URL dell'App Store. Ad esempio, 476943146 per l'app "Flood-It!" con link all'App Store https://apps.apple.com/us/app/flood-it/id476943146.

  • Per Android, la stringa ID è il nome del pacchetto dell'applicazione. Ad esempio, com.labpixies.flood per l'app "Flood-It!" con il link di Google Play https://play.google.com/store/apps/details?id=com.labpixies.flood.

Crea la richiesta

Per creare un segmento di pubblico Customer Match, crea una richiesta create per la risorsa UserList.

1. Imposta il campo parent sul nome della risorsa dell'account. Il nome della risorsa deve avere il formato accountTypes/{accountType}/accounts/{account}.

2. Utilizza il UserList che hai creato per il corpo della richiesta.

3. Se le tue credenziali non sono relative a un Account Google che è un utente di parent, imposta le intestazioni come descritto in Configura destinazioni e intestazioni.

Di seguito sono riportati esempi di richieste per creare un segmento di pubblico Customer Match con un membershipDuration di 30 giorni (2592000s). Seleziona la scheda REST e fai clic su Apri in Explorer API per provare una richiesta dal browser oppure seleziona la scheda per il linguaggio di programmazione scelto se hai installato una libreria client. Tieni presente che Display & Video 360 non supporta i segmenti di pubblico USER_ID, che sono inclusi negli esempi della libreria client.

REST

Dati di contatto

Apri in Explorer API

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

ID mobile

Apri in Explorer 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"
}

.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

Java

/**
 * 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

Nodo

/**
 * 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

Invia la richiesta

Invia la richiesta e, se necessario, includi intestazioni della richiesta come login-account o linked-account.

Se la richiesta ha esito positivo, la risposta contiene l'oggetto UserList creato con i campi di solo output id e name compilati.

Punto chiave: registra il id restituito sul UserList creato. Quando carichi o rimuovi membri del segmento di pubblico in una richiesta ingest, remove o removeAll, passa questo id come productDestinationId nel Destination della richiesta.

Se la richiesta non va a buon fine, esamina gli errori per determinare la causa dell'errore, aggiorna la richiesta e le intestazioni per risolvere eventuali problemi, quindi invia la richiesta e le intestazioni aggiornate.