ساختار فراخوانی 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 ) هستند که در بدنه درخواست همراه هستند:

مجوز

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

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

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

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

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate

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

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

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

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

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

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

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

• Authorization : یک توکن دسترسی OAuth 2.0 برای کاربری که به Partner دسترسی دارد.
• 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 trailing-metadata ) به همراه بدنه پاسخ برگردانده می‌شوند. توصیه می‌کنیم این مقادیر را برای اهداف اشکال‌زدایی ثبت کنید.

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

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