Эта страница переведена с помощью Cloud Translation API.

Отправить участников аудитории

Вы можете пройти это краткое руководство, чтобы ознакомиться с API Data Manager. Выберите версию краткого руководства, которую хотите просмотреть:

В этом кратком руководстве вы выполните следующие шаги:

Подготовьте Destination для получения данных об аудитории.
Подготовьте данные об аудитории для отправки.
Создайте запрос IngestionService для участников аудитории.
Отправьте запрос с помощью Google APIs Explorer.
Разберитесь в реакциях на успех и неудачу.

Подготовьте пункт назначения

Прежде чем отправлять данные, необходимо подготовить место назначения. Вот пример Destination , которое вы можете использовать. Примеры мест назначения для различных сценариев можно найти в разделе «Настройка мест назначения».

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

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

      "productDestinationId": "AUDIENCE_ID"
    }

Установите параметр operatingAccount равным типу учетной записи и идентификатору учетной записи, которая будет получать данные об аудитории.
Если ваши учетные данные OAuth предназначены для пользователя, имеющего доступ к учетной записи менеджера Google Ads , у которого operatingAccount является одной из суб-учетных записей, установите loginAccount равным типу учетной записи и идентификатору учетной записи менеджера.
Если учетные данные OAuth предназначены для пользователя, имеющего прямой доступ к operatingAccount , вам не нужно устанавливать loginAccount .

Подготовьте данные об аудитории.

Рассмотрим следующие примерные данные в файле, разделенном запятыми. Каждая строка в файле соответствует одному участнику аудитории, и каждый участник может иметь до трех адресов электронной почты.

#,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,

К адресам электронной почты предъявляются следующие требования к форматированию и хешированию:

Удалите все пробелы в начале, конце и в середине текста.
Преобразуйте адрес электронной почты в нижний регистр.
Хэшируйте адрес электронной почты, используя алгоритм SHA-256 .
Закодируйте байты хеша, используя шестнадцатеричное (hex) или Base64-кодирование . В примерах этого руководства используется шестнадцатеричное кодирование.

Вот отформатированные данные:

#,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,

А вот данные после хеширования и кодирования:

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

Вот пример объекта AudienceMember для отформатированных, хешированных и закодированных адресов электронной почты dana@example.com и danam@example.com из первой строки входных данных:

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

Сформируйте тело запроса.

Для формирования тела запроса объедините поля destinations и audienceMembers , установите поле encoding и добавьте любые другие поля запроса, которые вы хотите включить, такие как validateOnly и consent .

При отправке участников аудитории для функции «Подбор клиента» установите termsOfService , чтобы указать, принял ли пользователь условия предоставления услуг функции «Подбор клиента» .

В примерах этого руководства шифрование не используется, но вы можете следовать инструкциям в разделе «Шифрование пользовательских данных» , чтобы добавить шифрование в свой процесс.

Отправить запрос

Нажмите «Открыть в API Explorer» , чтобы открыть API Explorer в новой вкладке или окне.
В теле запроса в API Explorer замените каждую строку, начинающуюся с REPLACE_WITH , например REPLACE_WITH_OPERATING_ACCOUNT_TYPE , соответствующим значением.
Нажмите кнопку «Выполнить» в нижней части страницы API Explorer и заполните запросы на авторизацию, чтобы отправить запрос.
Установите validateOnly в true , чтобы проверить запрос без применения изменений. Когда вы будете готовы применить изменения, установите validateOnly в false .

Запрос на прием

Открыть style="border: 1px solid #1a73e8; padding: 4px; background-color: #1a73e8;">

{ "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 }

Ответы на вопросы об успехе

В случае успешного выполнения запроса возвращается ответ, содержащий объект с идентификатором requestId .

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

Запишите возвращаемый requestId , чтобы иметь возможность получать диагностические данные по мере обработки каждого пункта запроса.

Реакции на неудачу

В случае неудачной попытки запроса вы получите код ошибки, например, 400 Bad Request , а также подробный ответ с описанием ошибки.

Например, если emailAddress содержит обычную текстовую строку вместо шестнадцатеричного значения, ответ будет следующим:

{
  "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"
          }
        ]
      }
    ]
  }
}

Если emailAddress не хеширован и закодирован только в шестнадцатеричном формате, то в ответе будет получен следующий результат:

{
  "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"
          }
        ]
      }
    ]
  }
}

Отправка событий в несколько пунктов назначения

Если ваши данные содержат информацию об аудитории для разных направлений, вы можете отправить их в одном запросе, используя ссылки на направления.

Например, если у вас есть участник аудитории с ID 11112222 и другой участник аудитории с ID 77778888 , отправьте обоих участников в одном запросе, установив reference для каждого из Destination . reference определяется пользователем — единственное требование заключается в том, что каждый Destination должен иметь уникальную reference . Вот измененный список destinations для запроса:

  "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"
    }
  ]

Установите для destination_references каждого AudienceMember ссылку на один или несколько конкретных адресов назначения. Например, вот объект AudienceMember , предназначенный только для первого Destination , поэтому его список destination_references содержит только reference на первый Destination :

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

Поле destination_references представляет собой список, поэтому вы можете указать несколько пунктов назначения для участника аудитории. Если вы не зададите поле destination_references для объекта AudienceMember , API Data Manager отправит участника аудитории во все пункты назначения, указанные в запросе.

Следующие шаги

Настройте аутентификацию и создайте среду с клиентской библиотекой.
Изучите требования к форматированию, хешированию и кодированию для каждого типа данных.
Узнайте, как зашифровать пользовательские данные .
Узнайте, как получить диагностические данные для ваших запросов.
Узнайте о передовых методах .
Узнайте об ограничениях и квотах .

Общие сведения об аудиториях