إرسال أفراد الجمهور

يمكنك الاطّلاع على دليل التشغيل السريع هذا للتعرّف على Data Manager API. اختَر إصدار دليل التشغيل السريع الذي تريد الاطّلاع عليه:

في هذا التشغيل السريع، ستكمل الخطوات التالية:

  1. إعداد Destination لتلقّي بيانات الجمهور
  2. إعداد بيانات الجمهور لإرسالها
  3. إنشاء طلب IngestionService لأفراد الجمهور
  4. أرسِل الطلب باستخدام Google APIs Explorer.
  5. التعرّف على الردود التي تشير إلى النجاح أو الفشل

التحضير لرحلة إلى وجهة

قبل إرسال البيانات، عليك إعداد الوجهة التي سيتم إرسال البيانات إليها. إليك نموذج Destination يمكنك استخدامه:

    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • اضبط operatingAccount على المنتج ورقم تعريف الحساب الذي سيتلقّى بيانات شرائح الجمهور.

إعداد بيانات الجمهور

ضَع في اعتبارك نموذج البيانات التالي في ملف مفصول بفواصل. يتوافق كل سطر في الملف مع أحد أفراد الجمهور، ويمكن أن يتضمّن كل فرد ما يصل إلى ثلاثة عناوين بريد إلكتروني.

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

تتضمّن عناوين البريد الإلكتروني متطلبات التنسيق والتجزئة التالية:

  1. إزالة جميع المسافات البيضاء البادئة واللاحقة والمتوسطة
  2. تحويل عنوان البريد الإلكتروني إلى أحرف صغيرة
  3. جزِّئ عنوان البريد الإلكتروني باستخدام خوارزمية SHA-256.
  4. رمِّز وحدات البايت الخاصة بالتجزئة باستخدام الترميز السداسي العشري (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"
      }
    ]
  }
}

إنشاء نص الطلب

اجمع بين Destination وuserData لنص الطلب:

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "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
}
  1. عدِّل العناصر النائبة في النص الأساسي، مثل OPERATING_ACCOUNT_PRODUCT وOPERATING_ACCOUNT_ID وAUDIENCE_ID باستخدام قيم حسابك ووجهتك.
  2. اضبط قيمة validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.
  3. اضبط القيمة termsOfService للإشارة إلى أنّ المستخدم قد وافق على بنود خدمة "مطابقة العملاء".
  4. يُرجى العِلم أنّ هذا الطلب يشير إلى منح الإذن consent، ولا يستخدم التشفير.

إرسال الطلب

  1. انسخ نص الطلب باستخدام زر النسخ في أعلى يسار النموذج.
  2. انقر على الزر API في شريط الأدوات.
  3. ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
  4. انقر على الزر تنفيذ (Execute)، وأكمِل طلبات التفويض، وراجِع الردّ.

الردود الناجحة

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على requestId.

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

ردود الفشل

يؤدي الطلب غير الناجح إلى رمز حالة استجابة خطأ، مثل 400 Bad Request، واستجابة تتضمّن تفاصيل الخطأ.

على سبيل المثال، يؤدي email_address الذي يحتوي على سلسلة نصية عادية بدلاً من قيمة مشفّرة بنظام الستة عشر إلى إنتاج الرد التالي:

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

يؤدي استخدام email_address غير مجزّأ وله ترميز سداسي عشري فقط إلى عرض الاستجابة التالية:

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

الخطوات التالية