این راهنما ساختار مشترک همه فراخوانی‌های 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 تأیید شده باشد و درخواستی را با هدف حساب تولید ارسال کنید، میانای برنامه‌سازی کاربردی در نسخه ۲۵ و نسخه‌های جدیدتر 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/v26/customers/1234567890/campaignBudgets:mutate
تنظیم login-customer-id معادل انتخاب حساب در
رابط کاربری Google Ads پس‌از ورود به سیستم یا کلیک کردن روی تصویر نمایه در بالا سمت چپ است.
اگر این سرایند را اضافه نکنید، به‌طور پیش‌فرض به مشتری عامل برمی‌گردد.
شناسه مشتری پیوندشده
این سرایند الزامی است و شرکا (مثل ارائه‌دهندگان تجزیه‌وتحلیل برنامه طرف سوم یا شرکای داده) هنگام اقدام در حساب Google Ads پیوندشده از آن استفاده می‌کنند. این سرصفحه باید شناسه مشتری حساب Google Ads را که دارای پیوند محصول است مشخص کند.
سناریویی را درنظر بگیرید که در آن شریک باید براساس پیوند محصول، فراخوانی‌های میانای برنامه‌سازی کاربردی به حساب Google Ads انجام دهد.
- تبلیغ‌کننده: حساب 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
request-id رشته‌ای است که این درخواست را به‌طور منحصربه‌فرد شناسایی می‌کند. هنگام تماس با پشتیبانی، این مقدار را ارائه دهید تا به عیب‌یابی درخواست‌های API ناموفق یا غیرمنتظره کمک کند.