Se usó la API de Cloud Translation para traducir esta página.

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 objeto Destination para recibir datos de público.
Prepara los datos del 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:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_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.

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 de la dirección de correo electrónico con el algoritmo SHA-256.
Codifica los bytes del hash con codificación hexadecimal (hex) o 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

Combina Destination y userData para el cuerpo de la solicitud:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_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
}

Actualiza los marcadores de posición en el cuerpo, como OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID y AUDIENCE_ID, con los valores de tu cuenta y destino.
Establece validateOnly en true para validar la solicitud sin aplicar los cambios. Cuando esté todo listo para aplicar los cambios, establece validateOnly en false.
Establece termsOfService para indicar que el usuario aceptó las Condiciones del Servicio de Segmentación por clientes.
Ten en cuenta que esta solicitud indica que se otorgó consent y no usa encriptación.

Envía la solicitud

Copia el cuerpo de la solicitud con el botón de copia que se encuentra en la parte superior derecha del ejemplo.
Haz clic en el botón API de la barra de herramientas.
Pega el cuerpo de la solicitud copiado en el cuadro del Cuerpo de la solicitud.
Haz clic en el botón Ejecutar, completa las indicaciones de autorización y revisa la respuesta.

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 email_address 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 email_address 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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 parámetro destination_references de un objeto AudienceMember, la API del Administrador de datos 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