ساختار تماس API

این راهنما ساختار مشترک همه فراخوانی‌های API را شرح می‌دهد.

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

API گوگل ادز یک API مبتنی بر gRPC با اتصالات REST است. این بدان معناست که دو روش برای فراخوانی API وجود دارد.

ترجیح داده شده :

  1. بدنه درخواست را به عنوان یک بافر پروتکل ایجاد کنید.

  2. آن را با استفاده از HTTP/2 به سرور ارسال کنید.

  3. پاسخ را به یک بافر پروتکل deserialize کنید.

  4. نتایج را تفسیر کنید.

بیشتر مستندات ما استفاده از gRPC را شرح می‌دهند.

اختیاری :

  1. بدنه درخواست را به عنوان یک شیء JSON ایجاد کنید.

  2. آن را با استفاده از HTTP 1.1 به سرور ارسال کنید.

  3. پاسخ را به صورت یک شیء JSON از حالت سریال خارج کنید.

  4. نتایج را تفسیر کنید.

برای اطلاعات بیشتر در مورد استفاده از REST به راهنمای رابط REST مراجعه کنید.

نام منابع

بیشتر اشیاء در API توسط رشته‌های نام منابع خود شناسایی می‌شوند. این رشته‌ها هنگام استفاده از رابط REST به عنوان URL نیز عمل می‌کنند. برای ساختار آنها به نام‌های منابع رابط REST مراجعه کنید.

شناسه‌های مرکب

اگر شناسه یک شیء به صورت سراسری منحصر به فرد نباشد، یک شناسه مرکب برای آن شیء با اضافه کردن شناسه والد آن و یک علامت ~ به ابتدای آن ساخته می‌شود.

برای مثال، از آنجایی که شناسه تبلیغ یک گروه تبلیغاتی به صورت سراسری منحصر به فرد نیست، شناسه شیء والد (گروه تبلیغاتی) را به آن اضافه می‌کنیم تا یک شناسه ترکیبی منحصر به فرد ایجاد کنیم:

  • AdGroupId 123 + ~ + AdGroupAdId 45678 = شناسه تبلیغ گروه تبلیغاتی ترکیبی 123~45678 .

درخواست سربرگ‌ها

اینها هدرهای HTTP (یا متادیتای grpc ) هستند که در بدنه درخواست همراه هستند:

مجوز

شما باید یک توکن دسترسی OAuth2 را به شکل Authorization: Bearer YOUR_ACCESS_TOKEN وارد کنید که یا یک حساب مدیر را که به نمایندگی از یک مشتری عمل می‌کند، یا یک تبلیغ‌کننده که مستقیماً حساب خود را مدیریت می‌کند، مشخص می‌کند. دستورالعمل‌های بازیابی توکن دسترسی را می‌توانید در راهنمای OAuth2 بیابید. یک توکن دسترسی به مدت یک ساعت پس از دریافت آن معتبر است. پس از انقضا، توکن دسترسی را برای بازیابی توکن جدید به‌روزرسانی کنید. توجه داشته باشید که کتابخانه‌های کلاینت ما به طور خودکار توکن‌های منقضی شده را به‌روزرسانی می‌کنند.

اگر با خطاهای مجوز مواجه شدید، مطمئن شوید که از اعتبارنامه‌های صحیح استفاده می‌کنید و مجوزهای کافی دارید. خطای USER_PERMISSION_DENIED نشان می‌دهد که کاربر احراز هویت شده ممکن است به حساب مشتری مشخص شده در درخواست دسترسی نداشته باشد. برای جزئیات بیشتر در مورد مدیریت مجوزها، به سطوح دسترسی Google Ads مراجعه کنید.

توکن توسعه‌دهنده

توکن توسعه‌دهنده یک رشته ۲۲ کاراکتری است که به طور منحصر به فرد یک توسعه‌دهنده API تبلیغات گوگل را شناسایی می‌کند. یک نمونه از رشته توکن توسعه‌دهنده ABcdeFGH93KL-NOPQ_STUv است. توکن توسعه‌دهنده باید به شکل developer-token : ABcdeFGH93KL-NOPQ_STUv درج شود.

ورود-شناسه-مشتری

این شناسه مشتریِ مجاز برای استفاده در درخواست، بدون خط تیره ( - ) است. اگر دسترسی شما به حساب مشتری از طریق حساب مدیر است، این هدر الزامی است و باید روی شناسه مشتری حساب مدیر تنظیم شود. اگر هنگام احراز هویت از طریق حساب مدیر، login-customer-id را وارد نکنید، منجر به خطای AuthorizationError.USER_PERMISSION_DENIED می‌شود. برای اطلاعات بیشتر در مورد این نوع خطا، خطاهای رایج را بررسی کنید.

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

تنظیم login-customer-id معادل انتخاب یک حساب کاربری در رابط کاربری گوگل ادز پس از ورود به سیستم یا کلیک روی تصویر پروفایل شما در بالا سمت راست است. اگر این هدر را وارد نکنید، به طور پیش‌فرض روی operating customer قرار می‌گیرد.

شناسه مشتری مرتبط

این سربرگ توسط شرکا (مانند ارائه‌دهندگان تحلیل برنامه شخص ثالث یا شرکای داده) هنگام اقدام روی یک حساب Google Ads مرتبط مورد نیاز و استفاده است. این سربرگ باید شناسه مشتری حساب Google Ads که لینک محصول را دارد، مشخص کند.

سناریویی را در نظر بگیرید که در آن یک شریک نیاز دارد بر اساس یک لینک محصول، فراخوانی‌های API را به یک حساب Google Ads انجام دهد.

  • Advertiser : حساب کاربری گوگل ادز که توسط فراخوانی API مدیریت یا به‌روزرسانی می‌شود. شناسه حساب کاربری Advertiser در درخواست مشخص می‌شود. در REST، این پارامتر مسیر customerId است (برای مثال، customers/1111111111/... )، و در gRPC، این فیلد customer_id در درخواست است.
  • شریک : حساب شریک (برای مثال، یک ارائه‌دهنده تحلیل برنامه شخص ثالث یا شریک داده).
  • حساب کاربری مرتبط : حساب گوگل ادز که دارای یک لینک محصول مشخص با شریک است و به شریک دسترسی به تبلیغ‌کننده را می‌دهد.

کاربری که به Partner دسترسی دارد، فراخوانی‌های API را برای انجام اقدامات روی موجودیت‌های Advertiser انجام می‌دهد (برای مثال، برای آپلود تبدیل‌ها یا مدیریت لیست کاربران). حساب کاربری مرتبط می‌تواند خود Advertiser یا یک حساب کاربری مدیریتی Advertiser باشد.

هدرهای درخواست باید به صورت زیر تنظیم شوند:

  • Authorization : یک توکن OAuth2 برای کاربری که به Partner دسترسی دارد.
  • developer-token : توکن توسعه‌دهنده برای برنامه API که معمولاً با Partner مرتبط است.
  • login-customer-id : شناسه مشتری همکار. کاربر احراز هویت شده باید به این حساب دسترسی داشته باشد.
  • linked-customer-id : شناسه مشتری حساب لینک‌شده. این هدر نشان می‌دهد که مجوز این درخواست به لینک محصول حساب لینک‌شده با شریک متکی است.

دو سناریو برای لینک دادن وجود دارد:

  • اگر تبلیغ‌کننده لینک مستقیم محصول با شریک داشته باشد، حساب لینک‌شده تبلیغ‌کننده است و linked-customer-id باید روی شناسه مشتری تبلیغ‌کننده تنظیم شود.
  • اگر تبلیغ‌کننده توسط یک حساب مدیریتی که پیوند محصول با شریک دارد مدیریت می‌شود، حساب پیوند شده، حساب مدیریتی است و linked-customer-id باید روی شناسه مشتری مدیر تنظیم شود.

مثال ۱: لینک مستقیم

اگر تبلیغ‌کننده 1111111111 ارتباط مستقیمی با شریک 2222222222 داشته باشد، و فراخوانی API customers/1111111111/... را هدف قرار دهد:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

مثال ۲: لینک مدیریت

اگر تبلیغ‌کننده 1111111111 توسط مدیر 3333333333 مدیریت شود، مدیر 3333333333 با شریک 2222222222 پیوند دارد و فراخوانی API customers/1111111111/... را هدف قرار می‌دهد:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

هدرهای پاسخ

هدرهای زیر (یا grpc trailing-metadata ) به همراه بدنه پاسخ برگردانده می‌شوند. توصیه می‌کنیم این مقادیر را برای اهداف اشکال‌زدایی ثبت کنید.

شناسه درخواست

شناسه درخواست ( request-id رشته‌ای است که به طور منحصر به فرد این درخواست را مشخص می‌کند.

قبلی
فراداده منابع