صادرکردن داده از Apple Search Ads

Hermoso به Apple Search Ads وصل می‌شود و آن را به‌صورت ابزارهایی در اختیار عامل شما قرار می‌دهد که می‌تواند صدایشان بزند: Claude، ChatGPT، Cursor، Codex، Cline، CLI یا HTTP ساده. apple_ads_report عملکرد کمپین، گروه آگهی، آگهی، کلمه کلیدی و عبارت جستجو را می‌کشد، و ردیف‌ها به‌صورت داده برمی‌گردند، نه یک فایل CSV دانلودی که بعداً باید جای دیگری ببرید.

اتصال Apple Search Ads

Apple هیچ جریان OAuth برای API تبلیغاتش منتشر نمی‌کند، پس اتصال یک مبادلهٔ کلید است نه یک دکمه: Hermoso کلید امضا را می‌سازد، شما نیمهٔ عمومی آن را در Apple Ads می‌چسبانید و سه شناسه را برمی‌گردانید. راهنمای راه‌اندازی Apple Search Ads مراحل را توضیح می‌دهد، از جمله فیلد Public Key که بیشتر افراد پیدایش نمی‌کنند. یک اتصال، وب‌اپ، سرور MCP، CLI و REST API را با هم سرویس می‌دهد، پس همان صادرات از Claude، ChatGPT یا Cursor کار می‌کند: Apple Search Ads را به Claude وصل کنید یا به ChatGPT یک‌بار، سپس بپرسید.

گزارش‌گیری فقط بخشی از آن است. همان اتصال حساب را می‌سازد و اداره می‌کند: کمپین‌ها، گروه‌های آگهی، کلمات کلیدی و منفی‌ها، سفارش‌های بودجه، هدف‌گیری، پیشنهاد کلمات کلیدی و تاریخچهٔ تغییرات. صفحهٔ کانال Apple Ads همهٔ ابزارها را فهرست می‌کند.

گزارش چه چیزی دارد

یک فراخوانی، پنج سطح. apple_ads_report در سطح کمپین، گروه آگهی، آگهی، کلمه کلیدی یا عبارت جستجو گزارش می‌دهد، و هر ردیف معیارهایی را دارد که داشبورد خود Apple نشان می‌دهد: نمایش، تپ، نصب، هزینه، نرخ تپ، هزینهٔ هر تپ و هزینهٔ هر نصب. جمع کل بخواهید یا یک سری در دانه‌بندی ساعتی، روزانه، هفتگی یا ماهانه. ردیف‌ها بر اساس هزینه، از بیشترین به کمترین، تا ۵۰۰۰ ردیف در هر صفحه برمی‌گردند، با یک ردیف جمع کل در صورت درخواست. گزارش‌های App Store می‌توانند موجودیت‌های بدون تحویل هم داشته باشند، پس یک کلمه کلیدی متوقف به‌جای یک ردیف گم‌شده، صفر نشان داده می‌شود.

دو قاعدهٔ اعمال‌شده توسط Apple، که ابزار به‌جای شکست بی‌صدا توضیحشان می‌دهد: گزارشی زیر سطح کمپین به یک شناسهٔ کمپین نیاز دارد (فقط گزارش سطح کمپین می‌تواند کل حساب را پوشش دهد)، و گزارش‌های عبارت جستجو در منطقهٔ زمانی خود سازمان اجرا می‌شوند، نه UTC. آگهی‌های Apple Maps هم پوشش داده می‌شوند: یک گزارش business-brands از همان ابزار می‌آید با تغییر یک پارامتر.

اتصال Apple Search Ads به Google Sheets

این تنها مقصدی است که Hermoso خودش در آن می‌نویسد. Google Drive را کنار Apple Ads وصل کنید (یک مجوز Google هم Drive، هم Sheets و هم Docs را پوشش می‌دهد)، سپس بپرسید: «عملکرد Apple Search Ads را بر اساس کلمه کلیدی برای ۳۰ روز گذشته بکش و در یک صفحهٔ جدید به نام Apple Ads بگذار.» عامل apple_ads_report را صدا می‌زند، سپس create_sheet، و لینک را برمی‌گرداند. هفتهٔ بعد، همان درخواست با «افزودن» به‌جای شروع دوباره، ردیف‌ها را با append_to_sheet اضافه می‌کند.

Hermoso دامنهٔ drive.file گوگل را می‌خواهد، که فقط به فایل‌هایی که خودش ساخته یا شما انتخاب کرده‌اید دسترسی دارد، نه به کل Drive شما. راهنمای کامل، از جمله جایگزینی تب در جای خودش و قالب‌بندی آن، در اتصال Apple Search Ads به Google Sheets است.

صادرکردن Apple Search Ads به Looker Studio

Hermoso connector بومی برای Looker Studio ندارد، و ترجیح می‌دهیم این را بگوییم تا وانمود نکنیم که دارد. نیازی هم به آن ندارد: Looker Studio صفحات گسترده گوگل را با connector داخلی خودش می‌خواند، پس صفحهٔ بالا پل ارتباطی است.

1. بگذارید عامل گزارش را در یک تب بنویسد. دانه‌بندی روزانه، یک ردیف برای هر کلمه کلیدی در هر روز، یک ردیف سرتیتر و یک ستون تاریخ. از عامل بخواهید ستون تاریخ را به‌صورت تاریخ قالب‌بندی کند (format_sheet این کار را می‌کند) تا Looker Studio آن را تاریخ بخواند.
2. صفحه را به‌عنوان منبع داده اضافه کنید. در Looker Studio یک منبع داده بسازید، Google Sheets را انتخاب کنید، صفحه‌گسترده و آن تب را انتخاب کنید، و «Use first row as headers» را روشن نگه دارید.
3. گزارش را یک‌بار بسازید. هزینه بر حسب روز، هزینهٔ هر نصب بر حسب کلمه کلیدی، نصب‌ها بر حسب کمپین: هر چیزی که در غیر این صورت هر دوشنبه در یک صفحه‌گسترده دوباره می‌سازید.
4. افزودن را ادامه دهید. هر هفته عامل ردیف‌های جدید را به همان تب اضافه می‌کند و داشبورد در بازخوانی بعدی داده‌ها آن‌ها را می‌گیرد. نام ستون‌ها را بین اجراها یکسان نگه دارید، چون Looker Studio فیلدها را بر اساس سرتیتر تطبیق می‌دهد.

همان صفحه برای Power BI و Tableau هم کار می‌کند، که هر دو connector‌های Google Sheets خودشان را دارند.

صادرکردن Apple Search Ads به JSON

اگر ردیف‌های خام را می‌خواهید نه یک صفحه‌گسترده، سه راه برای گرفتن آن‌ها هست، همه با همان اتصال.

REST API. هر ابزار Hermoso در POST /v1/tools/{name} با یک کلید API که در برنامه، در تب MCP & CLI می‌سازید قابل فراخوانی است. بدنهٔ درخواست آرگومان‌های ابزار است و فیلد data پاسخ نتیجهٔ ساختاریافته است، با ردیف‌ها در data.rows:

curl -sX POST https://app.hermoso.ai/v1/tools/apple_ads_report \
  -H "Authorization: Bearer hmk_..." -H 'content-type: application/json' \
  -d '{"level":"keyword","campaignId":"1234567890","startTime":"2026-09-01","endTime":"2026-09-07","granularity":"DAILY"}' \
  | jq '.data.rows' > apple-search-ads.json

CLI. npx -y hermoso call apple_ads_report --json '{...}' --structured همان نتیجهٔ ساختاریافته را به‌صورت JSON چاپ می‌کند، آماده برای هدایت به یک فایل یا پایپ به یک اسکریپت دیگر.

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

برای گزارش‌های بزرگ، limit تا ۵۰۰۰ ردیف در هر صفحه می‌گیرد و offset به صفحهٔ بعدی می‌رود؛ hasMore در نتیجه نشان می‌دهد صفحهٔ دیگری وجود دارد یا نه. خواندن گزارش هیچ اعتباری مصرف نمی‌کند. مرجع کامل API در مستندات توسعه‌دهنده است.

مقصدهای دیگر

«مستقیم» یعنی Hermoso خودش می‌نویسد. بقیهٔ موارد یک قدم است که ابزاری که از قبل استفاده می‌کنید خودش انجام می‌دهد.

• Google Sheets، Google Docs، Google Drive، OneDrive: مستقیم.
• Looker Studio، Power BI، Tableau: از طریق صفحه، هر کدام با connector Google Sheets خودشان.
• BigQuery: از طریق صفحه، یا از طریق عامل خودتان. BigQuery می‌تواند یک Google Sheet را به‌عنوان جدول خارجی کوئری بزند. اگر عامل شما جایی اجرا می‌شود که کلاینت BigQuery و اعتبارنامه‌های پروژهٔ شما را دارد، می‌تواند ردیف‌هایی را که Hermoso برمی‌گرداند مستقیم در یک جدول درج کند.
• Excel: از طریق صفحه یا یک فایل. صفحه را به‌صورت .xlsx دانلود کنید، یا از عامل بخواهید فایلی را در Google Drive یا OneDrive بگذارد.
• PostgreSQL، Redshift، Snowflake یا هر انبار داده دیگر: از طریق عامل یا API خودتان. Hermoso JSON برمی‌گرداند؛ هر چیزی که اعتبارنامه‌های پایگاه داده‌تان را دارد آن را می‌نویسد. Hermoso اعتبارنامه‌های انبار داده را نگه نمی‌دارد.

خودکارسازی صادرات هفتگی

خود درخواست همان خودکارسازی است. چیزی مثل «هر دوشنبه، عملکرد Apple Search Ads هفتهٔ گذشته را بر اساس کلمه کلیدی برای همهٔ کمپین‌ها بکش، به صفحهٔ Apple Ads اضافه کن، و بگو کدام کلمات کلیدی بیشترین تغییر را در هزینهٔ هر نصب داشته‌اند» یک کار کامل است. آن را با زمان‌بندی‌ای که کلاینت شما از قبل دارد اجرا کنید (وظایف زمان‌بندی‌شده در Claude یا ChatGPT، یا یک cron job که CLI یا API Hermoso را صدا می‌زند) و صفحه، و هر داشبوردی که آن را می‌خواند، به‌روز می‌ماند.

چون همان اتصال حساب را هم ویرایش می‌کند، گزارش و اصلاح در یک جا هستند: عاملی که می‌بیند هزینهٔ هر نصب یک کلمه کلیدی دو برابر شده، می‌تواند همان‌جا در همان گفتگو آن را متوقف کند یا یک کلمهٔ منفی اضافه کند.

پرسش‌های متداول

چگونه داده‌ها را از Apple Search Ads صادر کنم؟

Apple Ads را یک‌بار به Hermoso وصل کنید، سپس از عامل گزارش موردنظرتان را بخواهید، برای مثال عملکرد کلمات کلیدی هفتهٔ گذشته. ابزار apple_ads_report آن را از API گزارش‌گیری Apple می‌کشد و عامل آن را در یک Google Sheet می‌نویسد، یا JSON به شما می‌دهد، یا هر دو.

آیا می‌توانم Apple Search Ads را به Google Sheets وصل کنم؟

بله. Apple Ads و Google Drive را در Hermoso وصل کنید، سپس از عامل بخواهید گزارش را در یک صفحه بگذارد. با create_sheet صفحهٔ جدید می‌سازد، یا با append_to_sheet ردیف‌ها را به یک صفحهٔ موجود اضافه می‌کند، و می‌تواند این کار را هر هفته تکرار کند.

آیا می‌توانم Apple Search Ads را به Looker Studio صادر کنم؟

بله، از طریق Google Sheets. Hermoso connector بومی Looker Studio ندارد. عامل گزارش را در یک صفحه می‌نویسد، شما آن صفحه را یک‌بار به‌عنوان منبع داده Google Sheets در Looker Studio اضافه می‌کنید، و هر افزوده در بازخوانی بعدی داشبورد نمایش داده می‌شود.

چگونه داده‌های Apple Search Ads را به JSON صادر کنم؟

POST /v1/tools/apple_ads_report را روی Hermoso API با یک کلید API صدا بزنید و data.rows را از پاسخ بخوانید، یا از CLI دستور hermoso call apple_ads_report را با --structured اجرا کنید. هر دو همان ردیف‌ها را به‌صورت JSON برمی‌گردانند.

آیا API گزارش‌گیری Apple Search Ads وجود دارد؟

بله، و Hermoso روی آن ساخته شده است. apple_ads_report عملکرد کمپین، گروه آگهی، آگهی، کلمه کلیدی و عبارت جستجو را پوشش می‌دهد، و ابزارهای دیگر Apple Ads حساب را می‌سازند و مدیریت می‌کنند.

آیا می‌توانم گزارش‌های عبارت جستجو را بگیرم؟

بله. سطح عبارت جستجو را بخواهید و نام کمپین را ذکر کنید. Apple عبارت‌های جستجو را فقط برای هر کمپین ارائه می‌دهد، در منطقهٔ زمانی خود سازمان.

یک گزارش چند ردیف می‌تواند برگرداند؟

تا ۵۰۰۰ در هر صفحه، مرتب‌شده بر اساس هزینه از بیشترین به کمترین، همراه با پرچمی که به عامل می‌گوید صفحهٔ بیشتری وجود دارد یا نه. گزارش هفتگی کلمات کلیدی برای بیشتر حساب‌ها در یک صفحه جا می‌شود.

آیا این آگهی‌های Apple Maps را هم پوشش می‌دهد؟

بله. گزارش‌های کمپین business-brands از همان ابزار می‌آیند، با نوع شیء ترفیع‌شده که به Apple Maps تنظیم شده به‌جای App Store.

آیا برای راه‌اندازی به توسعه‌دهنده نیاز دارم؟

نه. Apple Ads را یک‌بار در برنامه وصل کنید، سپس با عامل به زبان ساده صحبت کنید: گزارش هفتهٔ گذشته را بر اساس کلمه کلیدی بگیر و در یک صفحه بگذار. API و CLI هم هستند اگر بخواهید اسکریپت بنویسید.