Cómo enviar miembros del público

Puedes completar esta guía de inicio rápido para familiarizarte con la API de Data Manager. Elige la versión de la guía de inicio rápido que deseas ver:

En esta guía de inicio rápido, completarás los siguientes pasos:

Prepara un Destination para recibir datos de público.
Prepara los datos de público para enviarlos.
Crea una solicitud de IngestionService para los miembros del público.
Envía la solicitud con el Explorador de APIs de Google.
Comprende las respuestas de éxito y error.

Prepara un destino

Antes de enviar datos, debes preparar el destino al que los enviarás. Aquí tienes un ejemplo de Destination que puedes usar. Consulta Configura destinos para ver ejemplos de destinos para diferentes situaciones.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

Establece operatingAccount en el tipo de cuenta y el ID de la cuenta que recibirá los datos del público.
Si tus credenciales de OAuth son para un usuario con acceso a una cuenta de administrador de Google Ads que tiene operatingAccount como una de sus cuentas secundarias, establece loginAccount en el tipo de cuenta y el ID de la cuenta de administrador.
Si las credenciales de OAuth son para un usuario con acceso directo a operatingAccount, no es necesario que establezcas loginAccount.

Prepara los datos del público

Considera los siguientes datos de muestra en un archivo separado por comas. Cada línea del archivo corresponde a un miembro del público, y cada miembro tiene hasta tres direcciones de correo electrónico.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

Las direcciones de correo electrónico tienen los siguientes requisitos de formato y hash:

Quita todos los espacios en blanco iniciales, finales e intermedios.
Convierte la dirección de correo electrónico a minúsculas.
Genera un hash en la dirección de correo electrónico con el algoritmo SHA-256.
Codifica los bytes del hash con hexadecimal (hex) o codificación Base64. En los ejemplos de esta guía, se usa la codificación hexadecimal.

Estos son los datos con formato:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

Y aquí están los datos después de aplicarles el algoritmo de hash y la codificación:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

A continuación, se muestra un ejemplo de AudienceMember para las direcciones de correo electrónico con formato, codificación hash y codificación de dana@example.com y danam@example.com de la primera fila de los datos de entrada:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

Crea el cuerpo de la solicitud

Para crear el cuerpo de la solicitud, combina destinations y audienceMembers, configura el campo encoding y agrega cualquier otro campo de solicitud que quieras incluir, como validateOnly y consent.

Si envías miembros del público para la Segmentación por clientes, establece termsOfService para indicar si el usuario aceptó las condiciones del servicio de la Segmentación por clientes.

Los ejemplos de esta guía no usan encriptación, pero puedes seguir las instrucciones en Encripta los datos del usuario para agregar encriptación a tu proceso.

Envía la solicitud

Haz clic en Abrir en el Explorador de APIs para abrir el Explorador de APIs en una pestaña o ventana nueva.
En el cuerpo de la solicitud del Explorador de APIs, reemplaza cada cadena que comience con REPLACE_WITH, como REPLACE_WITH_OPERATING_ACCOUNT_TYPE, por el valor pertinente.
Haz clic en Ejecutar en la parte inferior de la página del Explorador de APIs y completa las indicaciones de autorización para enviar la solicitud.
Establece validateOnly en true para validar la solicitud sin aplicar los cambios. Cuando esté todo listo para aplicar los cambios, configura validateOnly en false.

Solicitud de transferencia

Abrir en el Explorador de APIs

{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_ACCOUNT_ID"
            },
            "productDestinationId": "AUDIENCE_ID"
        }
    ],
    "audienceMembers": [
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
                    },
                    {
                        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
                    },
                    {
                        "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
                    },
                    {
                        "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
                    },
                    {
                        "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
                    },
                    {
                        "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
                    }
                ]
            }
        }
    ],
    "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
    },
    "encoding": "HEX",
    "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
    },
    "validateOnly": true
}

Respuestas de éxito

Una solicitud correcta devuelve una respuesta con un objeto que contiene un requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Registra el requestId que se devolvió para que puedas recuperar los diagnósticos a medida que se procesa cada destino en la solicitud.

Respuestas de error

Una solicitud fallida genera un código de estado de respuesta de error, como 400 Bad Request, y una respuesta con detalles del error.

Por ejemplo, un emailAddress que contiene una cadena de texto sin formato en lugar de un valor codificado en hexadecimal produce la siguiente respuesta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Un emailAddress que no se hashea y solo se codifica en hexadecimal produce la siguiente respuesta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Envía eventos para varios destinos

Si tus datos contienen miembros del público para diferentes destinos, puedes enviarlos en la misma solicitud usando referencias de destino.

Por ejemplo, si tienes un miembro del público para el ID de la lista de usuarios 11112222 y otro miembro del público para el ID de la lista de usuarios 77778888, envía ambos miembros del público en una sola solicitud configurando el reference de cada Destination. El reference lo define el usuario. El único requisito es que cada Destination tenga un reference único. Esta es la lista de destinations modificada para la solicitud:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Establece el destination_references de cada AudienceMember para enviarlo a uno o más destinos específicos. Por ejemplo, aquí hay un AudienceMember que solo es para el primer Destination, por lo que su lista destination_references solo contiene el reference del primer Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

El campo destination_references es una lista, por lo que puedes especificar varios destinos para un miembro del público. Si no configuras el destination_references de un AudienceMember, la API de Data Manager envía al miembro del público a todos los destinos de la solicitud.

Próximos pasos

Configura la autenticación y tu entorno con una biblioteca cliente.
Obtén información sobre los requisitos de formato, hash y codificación para cada tipo de datos.
Obtén más información para encriptar datos del usuario.
Obtén información para recuperar diagnósticos de tus solicitudes.
Obtén más información sobre las prácticas recomendadas.
Obtén información sobre los límites y las cuotas.

Descripción general de los públicos