این راهنما ساختار مشترک همه فراخوانی‌های API را شرح می‌دهد.
اگر از کتابخانه مشتری برای تعامل با «میانای برنامه‌سازی کاربردی» استفاده می‌کنید، نیازی نیست جزئیات درخواست زیربنایی را بدانید. بااین‌حال، داشتن مقداری اطلاعات درباره ساختار فراخوانی API می‌تواند هنگام آزمایش و اشکال‌زدایی مفید باشد.
Google Ads API یک gRPC API با پیوندهای REST است. این یعنی دو روش برای برقراری تماس با API وجود دارد.
ترجیحی:
- بدنه درخواست را به‌عنوان بافر پروتکل ایجاد کنید.
- بااستفاده از HTTP/2 آن را به سرور ارسال کنید.
- پاسخ را به یک بافر پروتکل غیرسریال‌سازی کنید.
- نتایج را تفسیر کنید.
بیشتر مستندات ما استفاده از gRPC را شرح می‌دهد.
اختیاری:
- بدنه درخواست را به‌عنوان شیء JSON ایجاد کنید.
- بااستفاده از HTTP 1.1 آن را به سرور ارسال کنید.
- پاسخ را به‌عنوان شیء JSON واسریال‌سازی کنید.
- نتایج را تفسیر کنید.
برای اطلاعات بیشتر درباره استفاده از REST، به راهنمای میانای REST مراجعه کنید.
شناسه‌های منبع
اشیا در Google Ads API بااستفاده از نام‌های منبع ساختاری و شناسه‌های ترکیبی مورد خطاب قرار می‌گیرند.
نام‌های منبع
اکثر اشیا در API با رشته‌های نام منبع خود شناسایی می‌شوند. این رشته‌ها هنگام استفاده از میانای REST نیز به‌عنوان نشانی وب عمل می‌کنند. برای ساختار آن‌ها، «میانای REST» نام‌های منبع را ببینید.
شناسه‌های ترکیبی
اگر شناسه یک شیء در سطح جهانی یکتا نباشد، شناسه ترکیبی آن شیء با پیش‌افزودن شناسه والد آن و یک تیلدا (~) ساخته می‌شود.
برای مثال، AdGroupAd الگوی نام منبع customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} را دارد. زیرا شناسه ترکیبی آن شناسه گروه آگهی والد (ad_group.id) و شناسه آگهی زیرین (ad_group_ad.ad.id) را ترکیب می‌کند، شناسه گروه آگهی را به شناسه آگهی اضافه می‌کنیم:
-
AdGroupIdاز123+~+AdIdاز45678= گروه آگهی ترکیبی شناسه آگهی123~45678.
سرایندهای درخواست
این‌ها سرصفحه‌های HTTP (یا فراداده gRPC) هستند که بدنه درخواست را همراهی می‌کنند:
صدور مجوز
باید یک کد دسترسی OAuth 2.0 به‌شکل Authorization: Bearer
YOUR_ACCESS_TOKEN اضافه کنید که یا حساب مدیری را که ازطرف مشتری عمل می‌کند یا تبلیغ‌کننده‌ای را که مستقیماً حساب خود را مدیریت می‌کند شناسایی کند. دستورالعمل‌های
بازیابی کد دسترسی را می‌توانید در راهنمای OAuth2 پیدا کنید. نمودار دسترسی یک ساعت پس‌از دریافت آن معتبر است؛ وقتی منقضی شد، نمودار دسترسی را بازآوری کنید تا نمودار جدیدی دریافت کنید. توجه داشته باشید که کتابخانه‌های مشتری ما
به‌طور خودکار نشانه‌های منقضی‌شده را بازآوری می‌کنند.
اگر با خطاهای مجوز مواجه شدید، مطمئن شوید که از اطلاعات اعتباری صحیح استفاده می‌کنید و اجازه‌های کافی دارید. خطای USER_PERMISSION_DENIED نشان می‌دهد که کاربر اصالت‌سنجی‌شده ممکن است به حساب مشتری مشخص‌شده در درخواست دسترسی نداشته باشد. اگر پروژه Google Cloud شما فقط برای دسترسی Test تأیید شده باشد و درخواستی را ارسال کنید که حساب تولید را هدف‌یابی کند، API در نسخه ۲۵ و نسخه‌های جدیدتر AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION (یا در نسخه ۲۴ و نسخه‌های قدیمی‌تر AuthorizationError.ACTION_NOT_PERMITTED) را برمی‌گرداند.
برای جزئیات مربوط به مدیریت اجازه‌ها، به سطوح دسترسی Google Ads مراجعه کنید.
login-customer-id
این شناسه مشتری مجاز برای استفاده در درخواست است،
بدون خط تیره (-). اگر دسترسی شما به حساب مشتری ازطریق حساب
مدیر است، این سرایند الزامی است و باید روی شناسه مشتری حساب مدیر تنظیم شود. اگر هنگام اصالت‌سنجی ازطریق حساب مدیر، login-customer-id را اضافه نکنید، این کار منجر به خطای AuthorizationError.USER_PERMISSION_DENIED می‌شود. برای اطلاعات بیشتر درباره این نوع خطا، خطاهای رایج را مرور کنید. برای توضیح دقیق درباره نحوه حل‌وفصل دسترسی به حساب، به راهنمای مدل دسترسی OAuth مراجعه کنید.
https://googleads.googleapis.com/v25/customers/1234567890/campaignBudgets:mutate
تنظیم login-customer-id معادل انتخاب حساب در
واسط کاربر Google Ads پس‌از ورود به سیستم یا کلیک کردن روی تصویر نمایه در بالا سمت چپ است.
اگر این سرایند را اضافه نکنید، به‌طور پیش‌فرض به مشتری عامل برمی‌گردد.
شناسه مشتری پیوندشده
این سرایند الزامی است و شرکا (مثل ارائه‌دهندگان تجزیه‌وتحلیل برنامه طرف سوم یا شرکای داده) هنگام اقدام در حساب Google Ads پیوندشده از آن استفاده می‌کنند. این سرصفحه باید شناسه مشتری حساب Google Ads را که دارای پیوند محصول است مشخص کند.
سناریویی را درنظر بگیرید که در آن شریک باید براساس پیوند محصول با حساب Google Ads تماس API برقرار کند.
- تبلیغ‌کننده: حساب Google Ads که توسط تماس API مدیریت یا به‌روزرسانی می‌شود.
شناسه حساب «تبلیغ‌کننده» در درخواست مشخص شده است. در REST، این
پارامتر مسیر
customerId(برای مثال،customers/1111111111/...) است، و در gRPC، این فیلدcustomer_idدر درخواست است. - شریک: حساب شریک (برای نمونه، ارائه‌دهنده تجزیه‌وتحلیل برنامه طرف سوم یا شریک داده).
- حساب پیوندشده: حساب Google Ads که با «شریک» پیوند محصول برقرار کرده است و به «شریک» اجازه می‌دهد به «تبلیغ‌کننده» دسترسی داشته باشد.
کاربری که به حساب شریک دسترسی دارد، برای کنش روی نهادهای حساب تبلیغ‌کننده (برای مثال، برای بارگذاری تبدیل‌ها یا مدیریت فهرست‌های کاربر) تماس‌های API برقرار می‌کند. حساب پیوندشده می‌تواند خود حساب تبلیغ‌کننده یا حساب مدیر حساب تبلیغ‌کننده باشد.
سرصفحه‌های درخواست باید به‌صورت زیر تنظیم شوند:
Authorization: کد دسترسی OAuth 2.0 برای کاربری که به «شریک» دسترسی دارد.login-customer-id: شناسه مشتری حساب شریک. کاربر اصیل‌سازی‌شده باید به این حساب دسترسی داشته باشد.linked-customer-id: شناسه مشتری حساب پیوندی. این سرصفحه نشان می‌دهد که مجوز این درخواست به پیوند محصول «حساب پیوندی» با «شریک» بستگی دارد.
دو سناریو پیونددهی وجود دارد:
- اگر حساب تبلیغ‌کننده پیوند محصول مستقیم با حساب شریک داشته باشد،
حساب پیوندشده تبلیغ‌کننده است و
linked-customer-idباید روی شناسه مشتری حساب تبلیغ‌کننده تنظیم شود. - اگر حساب آگهی‌دهنده توسط حساب مدیری مدیریت شود که پیوند محصول با حساب شریک دارد، در این‌صورت حساب پیوندی حساب مدیر است و
linked-customer-idباید روی شناسه مشتری مدیر تنظیم شود.
مثال ۱: پیوند مستقیم
اگر حساب «تبلیغ‌کننده» 1111111111 با حساب «شریک» 2222222222 پیوند مستقیم داشته باشد و فراخوانی API customers/1111111111/... را هدف‌یابی کند:
Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
مثال ۲: پیوند مدیر
اگر حساب «تبلیغ‌کننده» 1111111111 توسط حساب مدیر
3333333333 مدیریت می‌شود، حساب مدیر 3333333333 با حساب «شریک»
2222222222 پیوند دارد، و فراخوانی API customers/1111111111/... را هدف‌یابی می‌کند:
Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
سرایندهای پاسخ
سرصفحه‌های زیر (یا فراداده انتهایی gRPC) با بدنه پاسخ برگردانده می‌شوند. توصیه می‌کنیم این مقادیر را برای اهداف اشکال‌زدایی ثبت کنید.
شناسه درخواست
request-id رشته‌ای است که این درخواست را به‌طور یکتا شناسایی می‌کند. این مقدار را هنگام تماس با پشتیبانی ارائه دهید تا به عیب‌یابی درخواست‌های ناموفق یا غیرمنتظره API کمک کند.