Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как зашифровать пользовательские данные

Data Manager API поддерживает шифрование данных с помощью следующих сервисов управления ключами:

Google Cloud Key Management Service
AWS Key Management Service

Поддержка некоторых сценариев зависит от сервиса управления ключами (KMS):

Категория	Пример использования	Google Cloud KMS	AWS KMS
Аудитории	Отправка участников аудитории
События	Офлайн-конверсии или расширенное отслеживание конверсий лидов
События	Конверсии – продажи в магазине в Google Рекламе
События	Конверсии Google Рекламы из нескольких источников
События	События Google Аналитики из нескольких источников

Как настроить Google Cloud KMS

Ниже описано, как настроить ресурсы Google Cloud KMS для шифрования.

Как настроить интерфейс командной строки Google Cloud

Установите и инициализируйте интерфейс командной строки Google Cloud.
Чтобы выбрать или создать проект Google Cloud и включить Cloud Key Management Service, нажмите Включить Cloud KMS.

Совет. Мы рекомендуем использовать для ресурсов Cloud KMS отдельный проект, который не содержит других ресурсов Google Cloud.

Включите Cloud KMS
Чтобы задать проект в среде, используйте команду gcloud config set. Чтобы проверить, задан ли проект в вашей среде, выполните команду gcloud config list.

Если переменная project не задана или вы хотите использовать для ключа другой проект, выполните команду gcloud config set:
```
gcloud config set project PROJECT_ID
```

Создать ключ

Дополнительную информацию можно найти в обзоре Cloud Key Management Service.

Создайте набор ключей.
```
gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION
```
Подробнее о том, как создать набор ключей…
Создайте ключ в наборе ключей. ROTATION_PERIOD указывает на интервал ротации ключа, а NEXT_ROTATION_TIME – на дату и время первой ротации.

Например, чтобы менять ключ каждые 30 дней и выполнить первую замену через неделю, задайте для ROTATION_PERIOD значение 30d, а для NEXT_ROTATION_TIME – $(date --utc --date="next week" --iso-8601=seconds).
```
gcloud kms keys create KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --purpose "encryption" \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time "NEXT_ROTATION_TIME"
```
Подробнее о том, как создать ключ…

Как создать поставщика пула Workload Identity

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

Создать пул Workload Identity. Для пула необходимо задать location global.
```
gcloud iam workload-identity-pools create WIP_ID \
   --location=global \
   --display-name="WIP_DISPLAY_NAME" \
   --description="WIP_DESCRIPTION"
```
Подробную информацию можно найти в статье Как управлять пулами Workload Identity и поставщиками.

Добавить поставщика в пул Workload Identity. Аргумент --attribute-condition подтверждает, что вызывающая функция является сервисным аккаунтом конфиденциального сопоставления.

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
   --location=global \
   --workload-identity-pool=WIP_ID \
   --display-name="PROVIDER_DISPLAY_NAME" \
   --description="PROVIDER_DESCRIPTION" \
   --attribute-mapping="google.subject=assertion.sub,google.groups=[\"PROVIDER_ID\"]" \
   --attribute-condition="assertion.swname == 'CONFIDENTIAL_SPACE' &&
     'STABLE' in assertion.submods.confidential_space.support_attributes &&
     ['cfm-services@admcloud-cfm-services.iam.gserviceaccount.com'].exists(
         a, a in assertion.google_service_accounts) &&
     'ECDSA_P256_SHA256:6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9'
     in assertion.submods.container.image_signatures.map(sig, sig.signature_algorithm+':'+sig.key_id)" \
   --issuer-uri="https://confidentialcomputing.googleapis.com" \
   --allowed-audiences="https://sts.googleapis.com"

Предоставьте роль дешифровщика ключа поставщику пула Workload Identity.

# Grants the role to the WIP provider.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "principalSet://iam.googleapis.com/projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/group/PROVIDER_ID" \
    --role "roles/cloudkms.cryptoKeyDecrypter"

Если вы хотите зашифровать данные о событиях для офлайн-конверсий и расширенного отслеживания конверсий лидов, предоставьте роль расшифровщика ключей сервисному аккаунту Google datamanager-api@datamanager-ga.iam.gserviceaccount.com.
```
# Grants the role to the Google service account.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "serviceAccount:datamanager-api@datamanager-ga.iam.gserviceaccount.com" \
    --role "roles/cloudkms.cryptoKeyDecrypter"
```

Перейдите к разделу Шифрование данных.

Настройте AWS KMS

Ниже описаны шаги по настройке ресурсов AWS KMS для шифрования.

Настройте интерфейс командной строки AWS

Установите интерфейс командной строки AWS.
Чтобы проверить установку, выполните следующую команду:
```
aws --version
```
Ниже приведен фрагмент выходных данных для успешной установки:
```
aws-cli/2.31.12 Python/3.13.7 ...
```

Настройте пользователя AWS и войдите в систему

Выполните необходимые условия для использования интерфейса командной строки AWS.
Войдите в сеанс IAM Identity Center.

Создать ключ

Создайте симметричный ключ KMS (KEK).
```
aws kms create-key \
  --key-usage ENCRYPT_DECRYPT \
  --key-spec SYMMETRIC_DEFAULT \
  --description "KEK for Confidential Matching Data Encryption"
```
Обратите внимание на Arn в разделе KeyMetadata. Вам понадобится Amazon Resource Name (ARN).
```
AWS_KEY_ARN
```
При необходимости создайте псевдоним ключа, используя выбранное вами название.
```
aws kms create-alias \
  --alias-name "alias/AWS_KEY_ALIAS" \
  --target-key-id AWS_KEY_ARN
```
Псевдоним не обязателен, но он может быть полезен при создании команд интерфейса командной строки AWS. Например, вы можете получить ARN ключа, используя псевдоним:
```
aws kms describe-key --key-id "alias/AWS_KEY_ALIAS" \
  --query 'KeyMetadata.Arn' \
  --output text
```

Как создать поставщика идентификационной информации OpenID Connect

Создайте поставщика идентификационной информации OpenID Connect (OIDC). Это нужно сделать лишь один раз для каждого аккаунта AWS.

aws iam create-open-id-connect-provider \
  --url https://confidentialcomputing.googleapis.com \
  --client-id-list AUDIENCE \
  --thumbprint-list "08745487e891c19e3078c1f2a07e452950ef36f6"

Запишите ARN поставщика OIDC из выходных данных. Она понадобится вам на следующих шагах.

AWS_OIDC_PROVIDER_ARN

Создайте политику IAM

Создайте JSON-файл с названием kms-decrypt-policy.json и следующим содержимым:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "AWS_KEY_ARN"
    }
  ]
}

Создайте правило IAM, используя файл JSON и название правила по вашему выбору.
```
aws iam create-policy \
  --policy-name "AWS_POLICY_NAME" \
  --policy-document file://kms-decrypt-policy.json
```
Запишите ARN правила IAM из выходных данных. Она понадобится вам на следующих шагах.
```
AWS_IAM_POLICY_ARN
```

Как создать и назначить роль IAM

Создайте файл JSON с названием role-trust-policy.json, содержащий указанные ниже данные и ARN поставщика OIDC, полученный на предыдущем шаге.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "AWS_OIDC_PROVIDER_ARN"
            },
            "Action": [
                "sts:AssumeRoleWithWebIdentity",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "confidentialcomputing.googleapis.com:aud": "cfm-awsresource",
                    "aws:RequestTag/swname": "CONFIDENTIAL_SPACE",
                    "aws:RequestTag/container.signatures.key_ids": "6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9"
                },
                "StringLike": {
                    "aws:RequestTag/confidential_space.support_attributes": "*STABLE*"
                }
            }
        }
    ]
}

Создайте роль IAM с нужным названием.

aws iam create-role \
  --role-name "AWS_IAM_ROLE_NAME" \
  --assume-role-policy-document file://role-trust-policy.json

Прикрепите правила роли к правилам IAM.

aws iam attach-role-policy \
  --role-name "AWS_IAM_ROLE_NAME" \
  --policy-arn "AWS_IAM_POLICY_ARN"

Шифрование данных

Для шифрования в Data Manager API требуется ключ шифрования данных (DEK). DEK – это симметричный ключ, который используется для шифрования данных. Ваш ключ шифрования данных зашифрован с помощью ключа шифрования ключа Google Cloud или AWS KMS. В запросе вы отправляете зашифрованный ключ шифрования данных, URI ключа шифрования ключей и поставщика WIP.

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

Не шифруйте нехешированные значения. Например, не хешируйте region_code, postal_code, city или administrative_area объекта AddressInfo.

После того как данные для каждого поля будут отформатированы и хешированы, зашифруйте значение хеша, выполнив следующие действия:

Закодируйте хешированные байты в формате Base64.

Внимание! На этом этапе необходимо использовать кодировку Base64. Шестнадцатеричное кодирование не поддерживается для хеша, созданного до шифрования. Если вы зашифруете хеш в шестнадцатеричной кодировке, Data Manager API не сможет расшифровать данные.
Зашифруйте хеш, закодированный в формате Base64, с помощью ключа шифрования данных. Поскольку требуется шифр XCHACHA20_POLY1305, функции encrypt() в Tink необходим параметр связанных данных. Этот параметр должен быть пустым (например, b"" в Python или new byte[0] в Java). Если вы передадите null или непустое значение, Data Manager API не сможет расшифровать данные.
Закодируйте результат шифрования в шестнадцатеричном формате или формате Base64.
Используйте закодированное значение для поля.
Задайте в запросе параметры encryption_info и encoding.

Чтобы завершить последний шаг, измените IngestAudienceMembersRequest или IngestEventsRequest, чтобы указать, что вы зашифровали данные:

Задайте поле encryption_info.
В поле encoding укажите кодировку, которая использовалась для шифрования значений полей.

Ниже приведен фрагмент запроса, в котором используется ключ Google Cloud KMS и заданы поля шифрования и кодирования.

{
  ...
  "encryptionInfo": {
    "gcpWrappedKeyInfo": {
      "kekUri": "gcp-kms://projects/PROJECT_ID/locations/KEY_RING_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME",
      "wipProvider": "projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/providers/PROVIDER_ID",
      "keyType": "XCHACHA20_POLY1305",
      "encryptedDek": "ENCRYPTED_DEK"
    }
  },
  "encoding": "ENCODING"
}

Чтобы создать и отправить запрос с помощью библиотеки и утилит Data Manager API, воспользуйтесь примером кода IngestAudienceMembers для Java или ingest_audience_members для Python.

Как проверить диагностику на наличие проблем с шифрованием

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

Как форматировать пользовательские данные

Как анализировать ошибки API

Как зашифровать пользовательские данные Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Как настроить Google Cloud KMS

Как настроить интерфейс командной строки Google Cloud

Создать ключ

Как создать поставщика пула Workload Identity

Настройте AWS KMS

Настройте интерфейс командной строки AWS

Настройте пользователя AWS и войдите в систему

Создать ключ

Как создать поставщика идентификационной информации OpenID Connect

Создайте политику IAM

Как создать и назначить роль IAM

Шифрование данных

Как проверить диагностику на наличие проблем с шифрованием

Как зашифровать пользовательские данные