التشغيل السريع

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

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

  1. حضِّر Destination لتلقّي بيانات الجمهور.
  2. حضِّر بيانات الجمهور لإرسالها.
  3. أنشئ طلب IngestionService.
  4. أرسِل الطلب باستخدام "مستكشف Google APIs".
  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. رمزِّ وحدات البايت الخاصة بالتجزئة باستخدام الترميز السداسي (الترميز السداسي) أو ترميز 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 للإشارة إلى أنّ المستخدم قد قبل بنود خدمة Match.
  4. يشير هذا الطلب إلى أنّه تم منح إذن consent، ولا يستخدم التشفير.

إرسال الطلب

  1. انسخ نص الطلب باستخدام زر النسخ في أعلى يسار العيّنة.
  2. انتقِل إلى صفحة audienceMembers.ingest.
  3. انقر على الزر واجهة برمجة التطبيقات على يسار الصفحة، ثم على الزر التجربة الآن في القسم الموسّع.
  4. ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
  5. انقر على الزر تنفيذ وأكمِل طلبات التفويض وراجِع الردّ.

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

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على 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"
          }
        ]
      }
    ]
  }
}

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