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

می توانید از طریق این شروع سریع کار کنید تا با Data Manager API آشنا شوید. نسخه شروع سریعی را که می خواهید ببینید انتخاب کنید:

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

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

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

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

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "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_TYPE ، 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"
}

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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 را تنظیم نکنید، Data Manager API مخاطب را به همه مقصدهای موجود در درخواست ارسال می کند.

مراحل بعدی

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