تستخدم 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، انقر على تفعيل 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 Federation. لمزيد من المعلومات، يُرجى الاطّلاع على اتحاد موفّري هويات خدمات المعالجة.

أنشئ مجموعة Workload Identity (WIP). يجب أن يكون 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"

امنح دور أداة فك تشفير المفاتيح لموفّر 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"

إذا أردت تشفير بيانات الأحداث للإحالات الناجحة غير الإلكترونية و"الإحالات الناجحة المحسّنة للعملاء المحتملين"، امنح دور فك تشفير المفتاح لحساب خدمة 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".

إنشاء مفتاح

أنشئ مفتاح KMS متماثل (KEK).

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

لاحظ Arn ضمن KeyMetadata في الناتج. ستحتاج إلى اسم مورد Amazon (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

إنشاء سياسة "إدارة الهوية وإمكانية الوصول"

أنشِئ ملف JSON باسم kms-decrypt-policy.json يتضمّن المحتوى التالي:

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

أنشئ سياسة "إدارة الهوية وإمكانية الوصول" باستخدام ملف JSON واسم سياسة من اختيارك.
```
aws iam create-policy \
  --policy-name "AWS_POLICY_NAME" \
  --policy-document file://kms-decrypt-policy.json
```
يُرجى تدوين اسم المورد الفريد (ARN) لسياسة "إدارة الهوية وإمكانية الوصول" في الناتج. ستحتاج إلى هذا الرمز في الخطوات الأخرى.
```
AWS_IAM_POLICY_ARN
```

إنشاء دور "إدارة الهوية وإمكانية الوصول" وإرفاقه

أنشئ ملف 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*"
                }
            }
        }
    ]
}

أنشئ دورًا في "إدارة الهوية وإمكانية الوصول" باسم من اختيارك.

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

أرفِق سياسة الدور بسياسة "إدارة الهوية وإمكانية الوصول".

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

تشفير البيانات

يتطلّب التشفير في Data Manager API مفتاح تشفير بيانات (DEK). مفتاح تشفير البيانات هو مفتاح متماثل يُستخدم لتشفير البيانات. يتم تشفير مفتاح DEK باستخدام مفتاح تشفير المفتاح (KEK) في Google Cloud أو AWS KMS. يتم إرسال مفتاح تشفير البيانات المشفّر ومعرّف الموارد المنتظم لمفتاح تشفير المفتاح وموفّر WIP كجزء من الطلب.

لإعداد البيانات في طلب التشفير، اتّبِع إرشادات التنسيق والتجزئة نفسها التي تستخدمها للبيانات غير المشفّرة.

لا تشفِّر القيم غير المجزّأة. على سبيل المثال، لا تجزِّئ region_code أو postal_code أو city أو administrative_area لـ AddressInfo.

بعد تنسيق البيانات لكل حقل وتجزئتها، يمكنك تشفير القيمة المجزّأة باتّباع الخطوات التالية:

رمِّز وحدات بايت التجزئة باستخدام ترميز Base64.

تنبيه: يجب استخدام ترميز Base64 لهذه الخطوة. لا يتوفّر ترميز نظام العد الستة عشري لتجزئة ما قبل التشفير. في حال تشفير تجزئة بترميز سداسي عشري، لن تتمكّن واجهة Data Manager API من فك تشفير البيانات.
شفِّر التجزئة المرمّزة بـ Base64 باستخدام مفتاح DEK. بما أنّ التشفير المطلوب هو 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. عليك معالجة أي تحذيرات في بيانات التشخيص، وإرسال الطلبات مرة أخرى، والتحقّق من أنّ بيانات التشخيص لم تعد تعرض تحذيرات بعد إجراء التغييرات.

تنسيق بيانات المستخدمين

التعرّف على أخطاء واجهة برمجة التطبيقات

تشفير بيانات المستخدمين تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إعداد Google Cloud KMS

إعداد واجهة سطر الأوامر في Google Cloud

إنشاء مفتاح

إنشاء موفّر لمجموعة Workload Identity

إعداد AWS KMS

إعداد واجهة سطر الأوامر في AWS

إعداد مستخدم AWS وتسجيل الدخول

إنشاء مفتاح

إنشاء موفِّر هوية OpenID Connect

إنشاء سياسة "إدارة الهوية وإمكانية الوصول"

إنشاء دور "إدارة الهوية وإمكانية الوصول" وإرفاقه

تشفير البيانات

الاطّلاع على بيانات التشخيص بحثًا عن مشاكل في التشفير

تشفير بيانات المستخدمين