Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Mã hoá dữ liệu người dùng

Data Manager API hỗ trợ mã hoá dữ liệu bằng các dịch vụ quản lý khoá sau:

Cloud Key Management Service của Google Cloud
AWS Key Management Service

Mức hỗ trợ cho một số trường hợp sử dụng sẽ khác nhau tuỳ theo dịch vụ quản lý khoá (KMS):

Danh mục	Trường hợp sử dụng	Google Cloud KMS	AWS KMS
Đối tượng	Gửi thành viên trong phân khúc đối tượng
Sự kiện	Lượt chuyển đổi ngoại tuyến hoặc lượt chuyển đổi nâng cao cho khách hàng tiềm năng
Sự kiện	Lượt chuyển đổi dạng lượt bán hàng tại cửa hàng thực tế trên Google Ads
Sự kiện	Lượt chuyển đổi từ nhiều nguồn trên Google Ads
Sự kiện	Sự kiện Google Analytics từ nhiều nguồn

Thiết lập Google Cloud KMS

Sau đây là các bước thiết lập tài nguyên Google Cloud KMS để mã hoá.

Thiết lập giao diện dòng lệnh của Google Cloud

Cài đặt và khởi động giao diện dòng lệnh của Google Cloud.
Để chọn hoặc tạo một dự án trên đám mây mới trên Google Cloud và bật Cloud Key Management Service, hãy nhấp vào Bật Cloud KMS.

Lưu ý: Bạn nên sử dụng một dự án riêng cho các tài nguyên Cloud KMS không chứa bất kỳ tài nguyên Google Cloud nào khác.

Bật Cloud KMS
Để đặt dự án trong môi trường của bạn, hãy sử dụng lệnh gcloud config set. Để kiểm tra xem dự án đã được thiết lập trong môi trường của bạn hay chưa, hãy chạy lệnh gcloud config list.

Nếu bạn chưa đặt project hoặc muốn sử dụng một dự án khác cho khoá, hãy chạy gcloud config set:
```
gcloud config set project PROJECT_ID
```

Tạo khoá

Để biết thêm thông tin, hãy xem bài viết Tổng quan về Cloud Key Management Service.

Tạo một bộ khoá.
```
gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION
```
Để biết thêm thông tin, hãy xem bài viết Tạo bộ khoá.
Tạo một khoá trong bộ khoá. ROTATION_PERIOD cho biết khoảng thời gian xoay vòng khoá và NEXT_ROTATION_TIME cho biết ngày và giờ diễn ra lần xoay vòng đầu tiên.

Ví dụ: để xoay vòng khoá sau mỗi 30 ngày và thực hiện lần xoay vòng đầu tiên sau 1 tuần, hãy đặt ROTATION_PERIOD thành 30d và NEXT_ROTATION_TIME thành $(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"
```
Để biết thêm thông tin, hãy xem bài viết Tạo khoá.

Tạo nhà cung cấp nhóm Workload Identity

Phần này trình bày thông tin tổng quan ngắn gọn về Liên kết Workload Identity. Để biết thêm thông tin, hãy xem phần Liên kết Workload Identity.

Tạo một nhóm Workload Identity (WIP). location cho nhóm phải là global.
```
gcloud iam workload-identity-pools create WIP_ID \
   --location=global \
   --display-name="WIP_DISPLAY_NAME" \
   --description="WIP_DESCRIPTION"
```
Để biết thêm thông tin, hãy xem bài viết Quản lý nhóm Workload Identity và nhà cung cấp.

Tạo một nhà cung cấp nhóm Workload Identity. Đối số --attribute-condition xác minh rằng phương thức gọi là tài khoản dịch vụ so khớp bí mật.

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"

Cấp vai trò của tiện ích giải mã khoá cho nhà cung cấp WIP.

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

Nếu bạn muốn mã hoá dữ liệu sự kiện cho lượt chuyển đổi ngoại tuyến và lượt chuyển đổi nâng cao cho khách hàng tiềm năng, hãy cấp vai trò giải mã khoá cho tài khoản dịch vụ 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"

Chuyển đến phần Mã hoá dữ liệu.

Thiết lập AWS KMS

Sau đây là các bước thiết lập tài nguyên AWS KMS để mã hoá.

Thiết lập Giao diện dòng lệnh AWS

Cài đặt Giao diện dòng lệnh AWS.
Chạy lệnh sau để xác minh quá trình cài đặt:
```
aws --version
```
Dưới đây là một đoạn mã kết quả cho một lượt cài đặt thành công:
```
aws-cli/2.31.12 Python/3.13.7 ...
```

Thiết lập người dùng AWS và đăng nhập

Hoàn tất các điều kiện tiên quyết để sử dụng Giao diện dòng lệnh AWS.
Đăng nhập vào một phiên IAM Identity Center.

Tạo khoá

Tạo khoá KMS đối xứng (KEK).

aws kms create-key \
  --key-usage ENCRYPT_DECRYPT \
  --key-spec SYMMETRIC_DEFAULT \
  --description "KEK for Confidential Matching Data Encryption"

Lưu ý Arn trong KeyMetadata ở kết quả. Bạn sẽ cần Tên tài nguyên Amazon (ARN) này trong các bước khác.

AWS_KEY_ARN

Không bắt buộc: Tạo bí danh khoá bằng tên bí danh mà bạn chọn.
```
aws kms create-alias \
  --alias-name "alias/AWS_KEY_ALIAS" \
  --target-key-id AWS_KEY_ARN
```
Bạn không bắt buộc phải đặt bí danh, nhưng bí danh sẽ hữu ích khi tạo các lệnh trong Giao diện dòng lệnh AWS. Ví dụ: bạn có thể truy xuất ARN khoá bằng cách sử dụng bí danh:
```
aws kms describe-key --key-id "alias/AWS_KEY_ALIAS" \
  --query 'KeyMetadata.Arn' \
  --output text
```

Tạo nhà cung cấp danh tính OpenID Connect

Tạo nhà cung cấp danh tính OpenID Connect (OIDC). Bạn chỉ cần thực hiện bước này một lần cho mỗi tài khoản AWS.

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

Ghi lại ARN của nhà cung cấp OIDC từ kết quả. Bạn sẽ cần mã này trong các bước khác.

AWS_OIDC_PROVIDER_ARN

Tạo chính sách IAM

Tạo một tệp JSON có tên là kms-decrypt-policy.json với nội dung sau:

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

Tạo chính sách IAM bằng tệp JSON và tên chính sách mà bạn chọn.
```
aws iam create-policy \
  --policy-name "AWS_POLICY_NAME" \
  --policy-document file://kms-decrypt-policy.json
```
Lưu ý ARN của chính sách IAM trong kết quả. Bạn sẽ cần mã này trong các bước khác.
```
AWS_IAM_POLICY_ARN
```

Tạo và đính kèm vai trò IAM

Tạo một tệp JSON có tên là role-trust-policy.json với nội dung sau đây và ARN của nhà cung cấp OIDC ở bước trước:

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

Tạo một vai trò IAM có tên vai trò mà bạn chọn.

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

Đính kèm chính sách vai trò vào chính sách IAM.

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

Mã hoá dữ liệu

Để mã hoá trong Data Manager API, bạn cần có khoá mã hoá dữ liệu (DEK). DEK là một khoá đối xứng mà bạn dùng để mã hoá dữ liệu. DEK của bạn được mã hoá bằng khoá mã hoá khoá (KEK) của Google Cloud hoặc AWS KMS. Bạn gửi DEK đã mã hoá, URI KEK và nhà cung cấp WIP trong yêu cầu.

Để chuẩn bị dữ liệu trong yêu cầu mã hoá, hãy làm theo nguyên tắc định dạng và băm tương tự như khi bạn sử dụng dữ liệu chưa mã hoá.

Đừng mã hoá các giá trị chưa băm. Ví dụ: đừng băm region_code, postal_code, city hoặc administrative_area của một AddressInfo.

Sau khi định dạng và băm dữ liệu cho từng trường, hãy mã hoá giá trị băm bằng các bước sau:

Mã hoá các byte băm bằng phương thức mã hoá Base64.

Thận trọng: Bạn phải sử dụng phương thức mã hoá Base64 cho bước này. Mã hoá thập lục phân không được hỗ trợ cho hàm băm trước khi mã hoá. Nếu bạn mã hoá một hàm băm được mã hoá thập lục phân, thì API Trình quản lý dữ liệu sẽ không thể giải mã dữ liệu đó.
Mã hoá hàm băm được mã hoá dưới dạng Base64 bằng DEK. Vì mật mã bắt buộc là XCHACHA20_POLY1305, nên hàm encrypt() của Tink yêu cầu một tham số dữ liệu liên kết. Tham số này phải trống (ví dụ: b"" trong Python hoặc new byte[0] trong Java). Nếu bạn truyền null hoặc một giá trị không trống, thì Data Manager API sẽ không thể giải mã dữ liệu.
Mã hoá kết quả của quá trình mã hoá bằng phương thức mã hoá thập lục phân hoặc Base64.
Sử dụng giá trị được mã hoá cho trường.
Đặt encryption_info và encoding trong yêu cầu.

Để hoàn tất bước cuối cùng, hãy sửa đổi IngestAudienceMembersRequest hoặc IngestEventsRequest để cho biết bạn đã mã hoá dữ liệu của mình:

Đặt trường encryption_info.
Đặt trường encoding thành phương thức mã hoá dùng để mã hoá các giá trị trường đã mã hoá.

Dưới đây là một đoạn mã của yêu cầu sử dụng khoá Google Cloud KMS và có đặt các trường mã hoá:

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

Để sử dụng thư viện và tiện ích của Data Manager API nhằm tạo và gửi yêu cầu, hãy xem mã mẫu IngestAudienceMembers cho Java hoặc mã mẫu ingest_audience_members cho Python.

Kiểm tra thông tin chẩn đoán để tìm vấn đề về mã hoá

Sau khi tải dữ liệu đã mã hoá lên, hãy sử dụng tính năng chẩn đoán để kiểm tra xem có cảnh báo nào liên quan đến việc mã hoá hay không, chẳng hạn như PROCESSING_WARNING_REASON_KEK_PERMISSION_DENIED hoặc PROCESSING_WARNING_REASON_DEK_DECRYPTION_ERROR. Giải quyết mọi cảnh báo trong thông tin chẩn đoán, gửi lại yêu cầu và xác minh rằng thông tin chẩn đoán không còn trả về cảnh báo sau khi bạn thay đổi.

Định dạng dữ liệu người dùng

Tiếp

Tìm hiểu về lỗi API

Mã hoá dữ liệu người dùng Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Thiết lập Google Cloud KMS

Thiết lập giao diện dòng lệnh của Google Cloud

Tạo khoá

Tạo nhà cung cấp nhóm Workload Identity

Thiết lập AWS KMS

Thiết lập Giao diện dòng lệnh AWS

Thiết lập người dùng AWS và đăng nhập

Tạo khoá

Tạo nhà cung cấp danh tính OpenID Connect

Tạo chính sách IAM

Tạo và đính kèm vai trò IAM

Mã hoá dữ liệu

Kiểm tra thông tin chẩn đoán để tìm vấn đề về mã hoá

Mã hoá dữ liệu người dùng