ساختار تماس API

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

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

Google Ads API یک API gRPC است که دارای اتصالات REST است. این بدان معنی است که دو راه برای برقراری تماس با API وجود دارد.

1. [ترجیح] بدنه درخواست را به عنوان یک بافر پروتکل ایجاد کنید، آن را با استفاده از HTTP/2 به سرور ارسال کنید، پاسخ به بافر پروتکل را از حالت سریال خارج کنید و نتایج را تفسیر کنید. بیشتر اسناد ما استفاده از gRPC را توصیف می کند.

2. [اختیاری] بدنه درخواست را به‌عنوان یک شی JSON ایجاد کنید، آن را با استفاده از HTTP 1.1 به سرور ارسال کنید، پاسخ را به‌عنوان یک شی JSON از فهرست خارج کنید و نتایج را تفسیر کنید. برای اطلاعات بیشتر در مورد استفاده از REST به راهنمای رابط REST مراجعه کنید.

نام منابع

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

شناسه های ترکیبی

اگر شناسه یک شی در سطح جهانی منحصر به فرد نباشد، یک شناسه ترکیبی برای آن شیء با اضافه کردن شناسه والد آن و یک tilde (~) ساخته می شود.

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

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

درخواست سرصفحه ها

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

مجوز

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

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

توکن توسعه دهنده یک رشته 22 کاراکتری است که به طور منحصر به فرد یک توسعه دهنده API Google Ads را شناسایی می کند. یک نمونه رشته توکن توسعه دهنده ABcdeFGH93KL-NOPQ_STUv است. توکن توسعه دهنده باید به شکل developer-token : ABcdeFGH93KL-NOPQ_STUv .

login-customer-id

این شناسه مشتری مشتری مجاز برای استفاده در درخواست، بدون خط تیره ( - ) است. اگر دسترسی شما به حساب مشتری از طریق حساب مدیر باشد، این هدر الزامی است و باید روی شناسه مشتری حساب مدیر تنظیم شود.

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

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

پیوند-مشتری-id

این سرصفحه تنها توسط ارائه‌دهندگان تجزیه و تحلیل برنامه شخص ثالث هنگام آپلود تبدیل‌ها به یک حساب Google Ads مرتبط استفاده می‌شود.

سناریویی را در نظر بگیرید که در آن کاربران در حساب A از طریق ThirdPartyAppAnalyticsLink دسترسی خواندن و ویرایش به موجودیت های آن به حساب B را ارائه می دهند. پس از پیوند، کاربر در حساب B می‌تواند با حساب A تماس‌های API برقرار کند، مشروط به مجوزهای ارائه شده توسط پیوند. در این مورد، مجوزهای فراخوانی API به حساب A توسط پیوند شخص ثالث به حساب B تعیین می شود، نه رابطه مدیر-حساب که در سایر تماس های API استفاده می شود.

ارائه‌دهنده تجزیه و تحلیل برنامه شخص ثالث یک تماس API به شرح زیر برقرار می‌کند:

• linked-customer-id : حساب تجزیه و تحلیل برنامه شخص ثالث که داده ها را آپلود می کند (حساب B ).
• customer-id : حساب Google Ads که داده ها در آن آپلود می شود (حساب A ).
• login-customer-id and Authorization header: ترکیبی از مقادیر برای شناسایی کاربری که به حساب B دسترسی دارد.

سرصفحه های پاسخ

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

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

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