API قبلی Search Ads 360 Reporting حذف می‌شود و در 30 ژوئن 2024 از رده خارج می‌شود. توجه داشته باشید که Search Ads 360 Conversion API تحت تأثیر قرار نگرفته و همچنان پشتیبانی می‌شود. همه توسعه گزارش‌های جدید باید از Search Ads 360 Reporting API جدید استفاده کنند.

از آوریل 2024، هنگام درخواست گزارش، یک خطای پشتیبانی‌نشده ApiVersion برگردانده می‌شود. جزئیات را اینجا ببینید.

همچنین اکیداً توصیه می‌کنیم که پیاده‌سازی‌های موجود Search Ads 360 را به API جدید منتقل کنید. برای اطلاعات بیشتر به راهنمای جدید Search Ads 360 Reporting Getting Started and Migration مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اولین برنامه شما: پیش نیازها

قبل از اینکه بتوانید اولین برنامه مشتری خود را کدنویسی کنید، اگر قبلاً آنها را انجام نداده اید، باید چند کار را انجام دهید.

یک حساب Google ایجاد کنید و مجوزهای Search Ads 360 را دریافت کنید

برای استفاده از Search Ads 360 API، به یک حساب Google و مجوزهای مناسب از Search Ads 360 به آن حساب اعطا شده است:

اگر قبلاً یک حساب Google ندارید، یک حساب ایجاد کنید .
از مدیر آژانس Search Ads 360 بخواهید که یک کاربر Search Ads 360 برای حساب Google شما ایجاد کند .
برای دانلود گزارش‌ها، به مجوز مشاهده برای تبلیغ‌کنندگانی که با آنها کار می‌کنید نیاز دارید.
برای افزودن یا ویرایش تبدیل‌ها، به مجوز ویرایش برای تبلیغ‌کنندگانی که با آنها کار می‌کنید نیاز دارید. در یک پیکربندی مشترک Floodlight ، برای هر تبلیغ‌کننده فرزندی که می‌خواهید تبدیل‌ها را در آن آپلود کنید، به مجوز ویرایش نیاز دارید. شما نیازی به دسترسی به تبلیغ‌کننده والد ندارید، همچنین نیازی به دسترسی به تبلیغ‌کنندگان فرزندی ندارید که تبدیل‌ها را در آنها آپلود نمی‌کنید. اگر از شناسه‌های کلیک برای نسبت دادن تبدیل به بازدیدها استفاده می‌کنید، مطمئن شوید که به تبلیغ‌کننده‌ای که شناسه کلیک را ایجاد کرده است، دسترسی ویرایش دارید. اگر شناسه کلیکی را از تبلیغ‌کننده‌ای که دسترسی ویرایش به آن ندارید مشخص کنید، درخواست موفق نخواهد شد.
مدیر آژانس می‌تواند حساب شما را به‌عنوان یک کاربر تبلیغ‌کننده با دسترسی به تبلیغ‌کنندگان خاص راه‌اندازی کند، یا حساب شما را با سطح دسترسی بالاتری مانند کاربر آژانس با دسترسی به همه تبلیغ‌کنندگان در آژانس راه‌اندازی کند.

سرویس تبدیل API را فعال کنید

اگر می‌خواهید داده‌های مربوط به تبدیل‌ها را آپلود کنید، کاربر Search Ads 360 با امتیازات Agency Manager باید وارد رابط کاربری Search Ads 360 شود و سرویس تبدیل API را فعال کند . برای دستورالعمل ها به مرکز راهنمای Search Ads 360 مراجعه کنید.

یک پروژه Google API Console و اعتبارنامه OAuth برای مشتری خود ایجاد کنید

ابزار تنظیم Google API Console را راه اندازی کنید.
ابزار راه‌اندازی شما را از طریق ایجاد یک پروژه (یا استفاده از یک پروژه موجود)، فعال کردن Search Ads 360 API و ایجاد اعتبارنامه OAuth 2.0 راهنمایی می‌کند.
در صفحه ثبت درخواست خود ، یک پروژه موجود را انتخاب کنید یا ایجاد پروژه را انتخاب کنید. سپس روی Continue کلیک کنید.
پس از اینکه Google API Console API Search Ads 360 را فعال کرد، روی دکمه Go to credentials کلیک کنید.
در صفحه Create credentials اطلاعات زیر را وارد کنید:
- از کدام API استفاده می کنید؟ : Search Ads 360 API
- به چه داده هایی دسترسی خواهید داشت؟ : داده های کاربر
روی دکمه Next کلیک کنید.
ابزار راه‌اندازی اکنون به شما کمک می‌کند تا یک شناسه مشتری OAuth 2.0 ایجاد کنید.
بقیه مراحل را در ابزار راه اندازی دنبال کنید.

sa360Api.py را نصب کنید

Search Ads 360 یک اسکریپت کاربردی برای تسهیل فرآیند تنظیم مجوز ارائه می دهد. همچنین می توانید از این اسکریپت برای ارسال و دریافت داده ها در قالب JSON استفاده کنید، اگر می خواهید قبل از طراحی و نوشتن یک برنامه کامل، ارسال و دریافت داده را امتحان کنید. می‌توانید بسیاری از نمونه‌های JSON را در این سایت مستندسازی کپی کرده و مستقیماً در اسکریپت وارد کنید.

برای نصب اسکریپت:

پایتون 2.7 را نصب کنید .
اسکریپت با Python 3.x کار نمی کند.
cURL را نصب کنید .
sa360Api.zip را دانلود کنید .
sa360Api.py از sa360Api.zip استخراج کنید.
sa360Api.py قابل اجرا کنید.

اصول REST را بیاموزید

دو راه برای فراخوانی API وجود دارد:

استفاده از کتابخانه های مشتری
ارسال درخواست های HTTP و تجزیه پاسخ ها.

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

REST سبکی از معماری نرم افزار است که یک رویکرد راحت و سازگار برای درخواست و اصلاح داده ها ارائه می دهد.

اصطلاح REST مخفف " انتقال دولت نمایندگی " است. در زمینه Google API ها، به استفاده از افعال HTTP برای بازیابی و اصلاح نمایش داده های ذخیره شده توسط Google اشاره دارد.

در یک سیستم RESTful، منابع در یک فروشگاه داده ذخیره می شوند. یک سرویس گیرنده درخواستی را ارسال می کند که سرور یک عمل خاص را انجام دهد (مانند ایجاد، بازیابی، به روز رسانی یا حذف یک منبع)، و سرور این عمل را انجام می دهد و پاسخی را می فرستد، اغلب به شکل یک نمایش از منبع مشخص شده.

در API های RESTful Google، مشتری با استفاده از یک فعل HTTP مانند POST ، GET ، PUT ، یا DELETE اقدامی را مشخص می کند. این یک منبع را توسط یک URI منحصر به فرد جهانی به شکل زیر مشخص می کند:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

از آنجایی که همه منابع API دارای URI های منحصر به فرد قابل دسترسی با HTTP هستند، REST ذخیره داده را فعال می کند و برای کار با زیرساخت های توزیع شده وب بهینه شده است.

ممکن است تعاریف روش را در مستندات استانداردهای HTTP 1.1 مفید بیابید. آنها شامل مشخصات GET ، POST ، PUT و DELETE هستند.

در Search Ads 360 API استراحت کنید

عملیات Search Ads 360 API مستقیماً به افعال HTTP REST نگاشت.

فرمت خاص برای URI های API Search Ads 360 این است:

https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters

مجموعه کامل URI های مورد استفاده برای هر عملیات پشتیبانی شده در API در مرجع API خلاصه شده است.

اصول JSON را بیاموزید

اگر از REST استفاده می کنید، باید از فرمت JSON برای بدنه های درخواست استفاده کنید. می توانید مشخص کنید که پاسخ ها در قالب JSON یا CSV باشند.

JSON (JavaScript Object Notation) یک قالب داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.