ارسال اعضای مخاطب

شما می‌توانید از طریق این راهنمای سریع با رابط برنامه‌نویسی کاربردی (API) مدیریت داده آشنا شوید. نسخه راهنمای سریعی را که می‌خواهید ببینید، انتخاب کنید:

در این راهنمای سریع، مراحل زیر را انجام می‌دهید:

  1. یک Destination برای دریافت داده‌های مخاطبان آماده کنید.
  2. داده‌های مخاطبان را برای ارسال آماده کنید.
  3. یک درخواست IngestionService برای اعضای مخاطب ایجاد کنید.
  4. درخواست را با Google APIs Explorer ارسال کنید.
  5. واکنش‌های موفقیت و شکست را درک کنید.

آماده کردن یک مقصد

قبل از اینکه بتوانید داده ارسال کنید، باید مقصدی را که می‌خواهید داده به آن ارسال شود، آماده کنید. در اینجا یک نمونه Destination برای استفاده شما آورده شده است:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  • operatingAccount را روی نوع حساب و شناسه حسابی که داده‌های مخاطب را دریافت خواهد کرد، تنظیم کنید.
  • اگر اعتبارنامه‌های OAuth شما برای کاربری است که به حساب مدیریت تبلیغات گوگل (Google Ads manager account) دسترسی دارد، که operatingAccount یکی از زیرحساب‌های آن است، loginAccount روی نوع حساب و شناسه حساب مدیریت تنظیم کنید.
  • اگر اعتبارنامه‌های OAuth برای کاربری با دسترسی مستقیم به operatingAccount است، نیازی به تنظیم loginAccount ندارید.

تهیه داده‌های مخاطبان

داده‌های نمونه زیر را در یک فایل جدا شده با کاما در نظر بگیرید. هر خط در فایل مربوط به یکی از اعضای مخاطب است و هر عضو حداکثر سه آدرس ایمیل دارد.

#,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. بایت‌های هش را با استفاده از کدگذاری هگزادسیمال (hexadecimal) یا 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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_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_TYPE ، OPERATING_ACCOUNT_ID و AUDIENCE_ID را با مقادیر حساب و مقصد خود به‌روزرسانی کنید.
  2. برای اعتبارسنجی درخواست بدون اعمال تغییرات، validateOnly روی true تنظیم کنید. وقتی آماده اعمال تغییرات شدید، validateOnly روی false تنظیم کنید.
  3. termsOfService طوری تنظیم کنید که نشان دهد کاربر شرایط خدمات Customer Match را پذیرفته است.
  4. توجه داشته باشید که این درخواست نشان می‌دهد که consent داده شده است و از رمزگذاری استفاده نمی‌کند.

درخواست را ارسال کنید

  1. متن درخواست را با استفاده از دکمه کپی در سمت راست بالای نمونه کپی کنید.
  2. روی دکمه API در نوار ابزار کلیک کنید.
  3. متن درخواست کپی شده را در کادر Request body قرار دهید.
  4. روی دکمه‌ی اجرا کلیک کنید، مراحل احراز هویت را تکمیل کنید و پاسخ را بررسی کنید.

پاسخ‌های موفقیت

یک درخواست موفق، پاسخی را با یک شیء حاوی requestId برمی‌گرداند.

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

requestId برگردانده شده را ثبت کنید تا بتوانید با پردازش هر مقصد در درخواست، عیب‌یابی را بازیابی کنید.

پاسخ‌های مربوط به شکست

یک درخواست ناموفق منجر به یک کد وضعیت پاسخ خطا مانند 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"
          }
        ]
      }
    ]
  }
}

ارسال رویدادها برای چندین مقصد

اگر داده‌های شما شامل مخاطبانی با مقاصد مختلف است، می‌توانید با استفاده از ارجاعات مقصد، آن‌ها را در یک درخواست واحد ارسال کنید.

برای مثال، اگر یک مخاطب با شناسه لیست کاربری 11112222 و یک مخاطب دیگر با شناسه لیست کاربری 77778888 دارید، هر دو مخاطب را در یک درخواست واحد با تنظیم reference هر Destination ارسال کنید. این reference توسط کاربر تعریف شده است - تنها شرط لازم این است که هر Destination یک reference منحصر به فرد داشته باشد. در اینجا لیست destinations اصلاح شده برای درخواست آمده است: 

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

destination_references هر AudienceMember را طوری تنظیم کنید که آن را به یک یا چند مقصد خاص ارسال کند. برای مثال، در اینجا یک AudienceMember وجود دارد که فقط برای اولین Destination است، بنابراین لیست destination_references آن فقط شامل reference اولین Destination است: 

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

فیلد destination_references یک لیست است، بنابراین می‌توانید چندین مقصد را برای یک عضو مخاطب مشخص کنید. اگر destination_references یک AudienceMember را تنظیم نکنید، رابط برنامه‌نویسی کاربردی (API) مدیر داده، عضو مخاطب را به تمام مقاصد موجود در درخواست ارسال می‌کند.

مراحل بعدی

قبلی
نمای کلی مخاطبان