گزارش‌دهی «پلاتفرم Google Maps»

گزارش‌دهی در Google Maps Platform مجموعه‌ای از گزارش‌های بصری ازپیش‌تعریف‌شده از مصرف پایه API، سهمیه، و اطلاعات صورت‌حساب را در کنسول Google Cloud ارائه می‌دهد. از این گزارش‌ها برای تعیین تعداد فراخوانی‌های میانای برنامه‌سازی کاربردی که انجام داده‌اید، میزان نزدیک بودن شما به سهمیه استفاده از میانای برنامه‌سازی کاربردی، و نظارت بر استفاده صورت‌حساب خود درطول زمان استفاده کنید.

انواع گزارش‌ها عبارت‌اند از:

• گزارش‌های استفاده: تعداد درخواست‌هایی را که پروژه شما بااستفاده از اطلاعات اعتباری مرتبط با پروژه‌تان به میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» ارسال می‌کند گزارش می‌کند.
• گزارش‌های سهمیه: مصرف سهمیه را در نمودارهایی گزارش می‌کند که می‌توانند براساس درخواست در دقیقه گروه‌بندی شوند. محدودیت‌های سهمیه فعلی برای APIهای انتخاب‌شده در جدول‌های زیر نمودارهای استفاده از سهمیه نمایش داده می‌شوند.
• گزارش‌های صورت‌حساب: هزینه‌ها را درطول زمان به‌صورت نمودار خطی پشته‌ای گزارش می‌کند. مشاهده میزان استفاده از سهمیه ماه جاری، شامل هرگونه اعتبار ویژه استفاده اعمال‌شده، و همچنین کل هزینه پیش‌بینی‌شده برای کل ماه جاری.

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

گزارش‌های استفاده، سهمیه، و صورت‌حساب Google Maps Platform را بااستفاده از کنسول Cloud مشاهده کنید.

گزارش‌های استفاده

استفاده براساس تعداد درخواست‌هایی است که پروژه شما بااستفاده از اطلاعات اعتباری منسوب به پروژه شما به میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» ارسال می‌کند. درخواست‌ها شامل درخواست‌های موفق، درخواست‌هایی که منجر به خطای سرور می‌شوند، و درخواست‌هایی که منجر به خطای کارخواه می‌شوند است. اعتبارنامه‌ها شامل کلیدهای API و شناسه‌های کارخواه (برای «طرح Premium» و پروژه‌های «طرح Premium» منتقل‌شده) است. برای جزئیات، نمای کلی طرح Premium و اطلاعات مربوط به استفاده از شناسه مشتری را ببینید.

سنجه‌های استفاده در جدول‌ها (درخواست‌ها، خطاها، و تأخیر) و نمودارها (ترافیک، خطاها، و تأخیر) نمایش داده می‌شود. برای اهداف ردیابی:

• همه میاناهای برنامه‌سازی کاربردی: می‌توانید سنجه‌های استفاده را برای همه میاناهای برنامه‌سازی کاربردی به این روش‌ها فیلتر و گروه‌بندی کنید:

  • فیلتر کردن براساس دوره زمانی و میانای برنامه‌سازی کاربردی.
  • ترافیک، خطا، و تأخیر را که براساس کد پاسخ، میانای برنامه‌سازی کاربردی، و اطلاعات کاربری گروه‌بندی شده‌اند ببینید.

• یک API خاص: می‌توانید سنجه‌های استفاده را برای یک API خاص به این روش‌ها فیلتر و گروه‌بندی کنید:

  • براساس دوره زمانی، نسخه‌های API، اعتبارنامه‌ها، و روش‌ها فیلتر کنید.
  • ترافیک، خطا، و تأخیر را که براساس کد پاسخ، روش و نسخه میانای برنامه‌سازی کاربردی، و اطلاعات کاربری گروه‌بندی شده‌اند ببینید.

صفحه داشبورد API-ها و سرویس‌ها

داشبورد «میاناهای برنامه‌سازی کاربردی و سرویس‌ها» نمای کلی‌ای از سنجه‌های استفاده برای همه میاناهای برنامه‌سازی کاربردی فعال‌شده برای پروژه‌تان ارائه می‌دهد: میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» و همچنین دیگر میاناهای برنامه‌سازی کاربردی و سرویس‌ها.

• صفحه داشبورد دارای سه نمودار و یک جدول است. می‌توانید مصرف نمایش‌داده‌شده در نمودارها و جدول‌ها را با انتخاب دوره زمانی از ۱ ساعت تا ۳۰ روز گذشته فیلتر کنید.

• نمودار ترافیک میزان استفاده را براساس پُرسمان در دقیقه (QPM) برای هر میانای برنامه‌سازی کاربردی نشان می‌دهد.

• نمودار خطاها درصد درخواست‌هایی را نشان می‌دهد که منجر به خطا در هر میانای برنامه‌سازی کاربردی شده‌اند.

• نمودار تأخیر میانه تأخیر درخواست‌ها را به‌ازای هر میانای برنامه‌سازی کاربردی نشان می‌دهد.

در زیر نمودارها، جدولی میاناهای برنامه‌نویسی کاربردی و سرویس‌های فعال‌شده را فهرست می‌کند. درخواست‌ها تعداد درخواست‌ها (برای دوره زمانی انتخاب‌شده) است. خطاها تعداد این درخواست‌ها است که منجر به خطا شده است. تأخیر (تأخیر متوسط و صدک) تأخیر این درخواست‌ها است.

برای دسترسی به صفحه «داشبورد میاناهای برنامه‌سازی کاربردی و سرویس‌ها»:

1. صفحه «انتخابگر پروژه» را در کنسول Cloud باز کنید:

   صفحه انتخابگر پروژه

2. پروژه‌تان را انتخاب کنید. صفحه «داشبورد سرویس‌ها و میاناهای برنامه‌سازی کاربردی» ظاهر می‌شود.
   
   اگر صفحه نشان داده نشد، دکمه منو و سپس APIs & Services (میاناهای برنامه‌سازی کاربردی و سرویس‌ها) را انتخاب کنید.

برای اطلاعات بیشتر، نظارت بر استفاده از میانای برنامه‌سازی کاربردی را ببینید.

صفحه نمای کلی Google Maps

صفحه نمای کلی Google Maps شامل جدولی است که میاناهای برنامه‌سازی کاربردی فعال‌شده و درخواست‌های استفاده در ۳۰ روز گذشته را فهرست می‌کند. درخواست‌های میانای برنامه‌سازی کاربردی نیز به‌صورت نمودار نشان داده می‌شود. نمودار صورت‌حساب، صورت‌حساب فعلی و کل مصرف شما را در ۳ ماه گذشته نشان می‌دهد.

توجه: اگر نام هرکدام از میاناهای برنامه‌سازی کاربردی فعال را انتخاب کنید، به صفحه سنجه‌های Google Maps برای آن میانای برنامه‌سازی کاربردی هدایت می‌شوید.

برای دسترسی به صفحه «نمای کلی پلاتفرم Google Maps»:

1. صفحه Google Maps Platform را در کنسول Cloud باز کنید:

   به صفحه Google Maps Platform بروید

2. در منوِ سمت راست، نمای کلی را انتخاب کنید.

صفحه «میاناهای برنامه‌سازی کاربردی و سرویس‌های پلاتفرم Google Maps»

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

برای دسترسی به صفحه «سرویس‌ها و میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps»:

1. صفحه Google Maps Platform را در کنسول Cloud باز کنید:

   به صفحه Google Maps Platform بروید

2. در منوِ سمت راست، میاناهای برنامه‌سازی کاربردی و سرویس‌ها را انتخاب کنید.

صفحه «سنجه‌های Google Maps»

صفحه سنجه‌های Google Maps سه نمودار را نمایش می‌دهد: ترافیک، خطاها، و تأخیر میانه. داده‌های استفاده در نمودارها را می‌توان براساس کلاس کد پاسخ، میانای برنامه‌سازی کاربردی، روش میانای برنامه‌سازی کاربردی، اطلاعات کاربری، پلاتفرم، و دامنه گروه‌بندی کرد.

در زیر نمودارها، صفحه سنجه‌ها شامل جدول میاناهای برنامه‌سازی کاربردی است که درخواست‌ها، خطاها، و تأخیر میاناهای برنامه‌سازی کاربردی انتخابی شما را نشان می‌دهد.

بااستفاده از منو کرکره‌ای API در بالا و گزینه‌های گروه‌بندی و فیلتر کردن در پانل سمت چپ، می‌توانید سنجه‌های استفاده نمایش‌داده‌شده را با انتخاب APIهای خاص یا چندگانه، اطلاعات کاربری، کلاس‌های کد پاسخ، نوع پلاتفرم و دامنه گروه‌بندی و فیلتر کنید. همچنین می‌توانید دوره زمانی (از یک ساعت تا ۳۰ روز گذشته) و دانه‌بندی (در ثانیه یا روز) را برای سنجه‌های استفاده نمایش‌داده‌شده انتخاب کنید.

توجه: گزینه‌های پلاتفرم و دامنه در فهرست کرکره‌ای گروه‌بندی‌شده براساس و فیلترهای پلاتفرم و دامنه برای انتخاب همه میاناهای برنامه‌سازی کاربردی Google Maps Platform از فهرست کرکره‌ای انتخاب میانای برنامه‌سازی کاربردی دردسترس نیستند. از انتخاب همه میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps برای تحلیل سطح بالا استفاده کنید: میاناهای برنامه‌سازی کاربردی و روش‌های دارای استفاده را پیدا کنید، نرخ‌های خطا و استفاده براساس اطلاعات کاربری را بررسی کنید. برای بررسی عمیق‌تر تجزیه‌وتحلیل یک API خاص، آن API را از فهرست کرکره‌ای انتخاب API انتخاب کنید. هنگام انتخاب یک API خاص از فهرست کرکره‌ای انتخاب API، می‌توانید تحلیل دقیق‌تری برای استفاده از API انجام دهید، مانند گروه‌بندی و فیلتر کردن براساس پلاتفرم و دامنه.

تصاویر زیر فیلترهای پلاتفرم و دامنه را برای یک API خاص نشان می‌دهند وقتی گروه‌بندی براساس پلاتفرم و دامنه در فهرست کرکره‌ای گروه‌بندی براساس انتخاب شده است:

برای دسترسی به صفحه «سنجه‌های میانای برنامه‌سازی کاربردی پلاتفرم Google Maps»:

1. صفحه Google Maps Platform را در کنسول Cloud باز کنید:

   به صفحه Google Maps Platform بروید

2. در منوِ سمت راست، سنجه‌ها را انتخاب کنید.

گزارش کردن اطلاعات اعتباری

می‌توانید سنجه‌ها را براساس اطلاعات اعتباری که برای بار کردن API استفاده شده است فیلتر و گروه‌بندی کنید.

قالب اعتبارنامه	معنی
نام کلید برای مثال، «کلید برنامه تلفن همراه»	از کلید میانای برنامه‌سازی کاربردی برای بار کردن میانای برنامه‌سازی کاربردی استفاده شده است بااستفاده از ?key=...: می‌توانید نام کلیدها را در کنسول Maps Platform در بخش کلیدها و اطلاعات کاربری پیدا کنید.
شماره پروژه برای مثال، «project_number:123456» که 123456 شماره پروژه شما است.	اگر این اطلاعات اعتباری را می‌بینید، دو احتمال وجود دارد: برای میاناهای برنامه‌سازی کاربردی که شناسه‌های کارخواه Maps Platform را می‌پذیرند: از شناسه کارخواه Maps Platform برای بار کردن میانای برنامه‌سازی کاربردی استفاده شده است. برای مثال، بااستفاده از &client=gme-_mycompany_. این میاناهای برنامه‌سازی کاربردی شناسه‌های کارخواه را می‌پذیرند: Maps JavaScript API،‏ Maps Static API،‏ Street View Static API،‏ Elevation API،‏ Directions API (قدیمی)، Distance Matrix API (قدیمی)، Geocoding API،‏ Time Zone API. برای اطلاعات بیشتر، مدیریت شناسه مشتری طرح Premium را ببینید. برای میاناهای برنامه‌سازی کاربردی که OAuth را می‌پذیرند: میانای برنامه‌سازی کاربردی بااستفاده از OAuth بدون کلید میانای برنامه‌سازی کاربردی بار شد.

توجه: هیچ میانای برنامه‌سازی کاربردی‌ای در «پلاتفرم Maps» وجود ندارد که هم از شناسه‌های کارخواه «پلاتفرم Maps» و هم از OAuth پشتیبانی کند، بنابراین می‌توانید براساس میانای برنامه‌سازی کاربردی استفاده‌شده تشخیص دهید که میانای برنامه‌سازی کاربردی با شناسه کارخواه بار شده است یا OAuth.

نمودارهای کد پاسخ

نمودارهای ترافیک براساس کد پاسخ و خطا براساس کد پاسخ استفاده را براساس کلاس کد پاسخ HTTP تقسیم می‌کنند. این جدول نگاشت بین وضعیت پاسخ Google Maps Platform API و کلاس کد پاسخ HTTP را نشان می‌دهد:

وضعیت Maps API	کلاس کد پاسخ‌های HTTP - گزارش استفاده (2xx،‏ 3xx،‏ 4xx،‏ 5xx)	یادداشت‌ها
تأیید	2xx	پاسخ موفق. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
تأیید	3xx	پاسخ موفق. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد. برای مثال، درخواست‌های موفق عکس مکان بازگشت ۳۰۲ را به تصویر ارجاع‌شده هدایت می‌کند.
DATA_NOT_AVAILABLE	‫4xx^(۱)	پاسخ موفقیت‌آمیز نشان می‌دهد که هیچ داده‌ای برای مکان‌های ورودی دردسترس نیست. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
ZERO_RESULTS	‫4xx^(۱)	پاسخ موفقیت‌آمیز نتیجه‌ای برنگرداند. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
NOT_FOUND	‫4xx^(۱)	برای Directions API (Legacy)، این پیام نشان می‌دهد که حداقل یکی از مکان‌های مشخص‌شده در مبدأ، مقصد، یا نقاط‌مسیر درخواست زمین‌کدیابی نشده است. برای Places API این پیام نشان می‌دهد که مکان ارجاع‌شده (place_id) در پایگاه داده Places پیدا نشده است. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
INVALID_REQUEST (مقدار پارامتر نامعتبر)، MAX_WAYPOINTS_EXCEEDED، MAX_ROUTE_LENGTH_EXCEEDED، و غیره.	4xx	خطا به‌دلیل مقدار نامعتبر پارامتر ایجاد شده است. برای جزئیات بیشتر، پاسخ میانای برنامه‌سازی کاربردی را بررسی کنید. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
REQUEST_DENIED	4xx	خطای کارخواه ناشی از خطای اصالت‌سنجی، خطای دسترسی، و غیره. برای جزئیات بیشتر، پاسخ میانای برنامه‌سازی کاربردی را بررسی کنید.
OVER_DAILY_LIMIT, OVER_QUERY_LIMIT, RESOURCE_EXHAUSTED, rateLimitExceeded, dailyLimitExceeded, userRateLimitExceeded	4xx	خطای کارخواه به‌دلیل درخواست‌های بسیار زیاد در دوره زمانی مجاز. درخواست را بعداً دوباره امتحان کنید. برای جزئیات بیشتر، پاسخ میانای برنامه‌سازی کاربردی را بررسی کنید.
INVALID_REQUEST (پارامتر نامعتبر یا مفقود، درخواست تجزیه یا خطای اعتبارسنجی)	4xx	خطای کارخواه به‌دلیل درخواست نامعتبر. برای جزئیات بیشتر، پاسخ میانای برنامه‌سازی کاربردی را بررسی کنید.
NOT_FOUND (404)	4xx	برای Directions API (Legacy)، این پیام نشان می‌دهد که حداقل یکی از مکان‌های مشخص‌شده در مبدأ، مقصد، یا نقاط‌مسیر درخواست زمین‌کدیابی نشده است. برای Geolocation API، این پیام نشان می‌دهد که ورودی‌ها برای تولید تخمین مکان کافی نبوده‌اند. برای Roads API، این پیام نشان می‌دهد که ورودی‌ها را نمی‌توان به‌طور منطقی به جاده‌ها هم‌تراز کرد. این درخواست قابل‌صورت‌حساب است و سهمیه مصرف خواهد کرد.
UNKNOWN_ERROR	‫5xx	خطای سرور نشان می‌دهد که درخواست نمی‌تواند ادامه یابد: خطای داخلی، بارگذاری بیش‌ازحد سرویس، دردسترس نبودن، اتمام مهلت، و غیره.

^۱ برای بهبود سازگاری گزارش کد خطا، میاناهای برنامه‌سازی کاربردی Google Maps Platform در حال انتقال هستند: ۱) از کلاس کد پاسخ HTTP‏ 2xx به 4xx برای وضعیت‌های Maps API: ‏DATA_NOT_AVAILABLE، ‏NOT_FOUND، ZERO_RESULTS - وضعیت، ۲) از کلاس کد پاسخ HTTP‏ 2xx به 4xx برای وضعیت‌های Maps API: ‏REQUEST_DENIED، ‏OVER_DAILY_LIMIT، OVER_QUERY_LIMIT، ‏dailyLimitExceeded، rateLimitExceeded، ‏userRateLimitExceeded، ۳) از کلاس کد پاسخ HTTP‏ 2xx به 5xx برای وضعیت Maps API: ‏UNKNOWN_ERROR. می‌توانید هر دو کد پاسخ را درطول دوره انتقال ببینید. کدهای پاسخ برگردانده‌شده در پاسخ‌های Maps API تغییر نمی‌کنند. با بررسی اینکه دقیقاً کدام کد پاسخ در کاوشگر سنجه‌ها افزایش می‌یابد، تأیید کنید که افزایش در 4xx و/یا 5xx در سنجه‌های پلاتفرم Google Maps به این انتقال مربوط است (درباره استفاده از Google Cloud Monitoring برای «پلاتفرم Google Maps» بیشتر بدانید).

برای اطلاعات بیشتر درباره کدهای وضعیت و پیام‌های خطا، به اسناد پاسخ برای میانای برنامه‌سازی کاربردی موردنظرتان (برای مثال، پاسخ‌های زمین‌کدیابی یا پاسخ‌های مسیرها) مراجعه کنید.

پارامتر ارجاع استفاده از «پلاتفرم Google Maps»

«پلاتفرم Google Maps» انواع مختلفی از کد نمونه ارائه می‌دهد تا به شما کمک کند به‌سرعت راه‌اندازی کنید و اجرا کنید. برای مثال، می‌توانید از Quick Builder در کنسول Cloud استفاده کنید، راهکارهای صنعتی راهنماهای پیاده‌سازی را دنبال کنید، و از codelabs یاد بگیرید.

برای درک استفاده و راه‌های بهبود راه‌حل‌هایمان، Google پارامتر internal_usage_attribution_ids را در فراخوانی‌های API برای جمع‌آوری اطلاعات درباره استفاده از کد نمونه اضافه می‌کند:

• پارامتر internal_usage_attribution_ids ممکن است به‌طور پیش‌فرض در کد نمونه راه‌حل گنجانده شود.
• این پارامتر تجزیه‌وتحلیل‌های مربوط به پذیرش راه‌حل را به Google برمی‌گرداند تا کیفیت راه‌حل در تکرارهای آینده بهبود یابد.
• می‌توانید با حذف کردن پارامتر internal_usage_attribution_ids و مقدار آن از کد نمونه، انصراف دهید.
• نیازی به حفظ پارامتر نیست. برداشتن پارامتر تأثیری بر عملکرد ندارد.
• این پارامتر فقط برای گزارش استفاده از کدگذاری نمونه استفاده می‌شود.
• این پارامتر از هرگونه تجزیه‌وتحلیل و گزارش‌دهی مختص میانای برنامه‌سازی کاربردی جدا است. این یعنی برداشتن پارامتر از کد نمونه راه‌حل باعث غیرفعال شدن گزارش‌دهی داخلی Maps JavaScript API نمی‌شود.

توجه: پارامتر solution_channel همچنان معتبر است و ممکن است در پیاده‌سازی‌های موجود یافت شود، اما دیگر توصیه نمی‌شود. درعوض از internal_usage_attribution_ids استفاده کنید.

گزارش‌های سهمیه

سهمیه‌ها برای تعداد درخواست‌هایی که پروژه شما می‌تواند به میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» ارسال کند حد تعیین می‌کنند. درخواست‌ها را می‌توان به سه روش محدود کرد: در روز، در دقیقه، و برای هر کاربر در دقیقه. فقط درخواست‌های موفق و درخواست‌هایی که موجب خطای سرور می‌شوند در سهمیه محاسبه می‌شوند. درخواست‌هایی که اصالت‌سنجی نمی‌شوند در سهمیه محاسبه نمی‌شوند.

استفاده از سهمیه در نمودارهای صفحه سهمیه‌ها در کنسول Cloud نمایش داده می‌شود و می‌تواند براساس درخواست‌ها در دقیقه گروه‌بندی شود. محدودیت‌های سهمیه فعلی برای APIهای انتخاب‌شده در جدول‌های زیر نمودارهای استفاده از سهمیه نمایش داده می‌شود.

برای دریافت مقدار سهمیه دقیقه‌ای برای هر محصول GMP API، از این ماشین‌حساب استفاده کنید.

صفحه سهمیه‌های Google Maps

صفحه سهمیه‌ها در Google Maps محدودیت‌های سهمیه و مصرف سهمیه را برای API خاصی که انتخاب کرده‌اید نشان می‌دهد.

نمودار استفاده از سهمیه در کنسول Google Cloud کل ترافیک کلیدهای API و شناسه‌های مشتری شما را نشان می‌دهد. ترافیک شناسه کارخواه در نمودار «سنجه‌ها» در کنسول Cloud نیز دردسترس است.

این صفحه فقط درخواست‌هایی را نشان می‌دهد که سهمیه مصرف می‌کنند: درخواست‌های موفق (OK، ZERO_RESULTS، DATA_NOT_AVAILABLE) و درخواست‌هایی که باعث خطاهای سرور می‌شوند (NOT_FOUND، INVALID_REQUEST/INVALID_VALUE (مقدار پارامتر نامعتبر)، و UNKNOWN_ERROR).

درخواست‌هایی که باعث خطاهای کارخواه می‌شوند — خطاهای اصالت‌سنجی، صدور مجوز، و متغیر مستقل نامعتبر (REQUEST_DENIED، OVER_QUERY_LIMIT، INVALID_REQUEST (پارامتر نامعتبر، خطای تجزیه درخواست)) — سهمیه مصرف نمی‌کنند و نمایش داده نمی‌شوند.

واحد سهمیه برای اکثر میاناهای برنامه‌سازی کاربردی Google Maps Platform ( Maps Static API،‏ Street View Static API، Geocoding API،‏ Directions API (قدیمی)، Places API،‏ Time Zone API، Geolocation API، و Elevation API) درخواست است، اما استثناهایی وجود دارد:

• برای Distance Matrix API (قدیمی)، واحد سهمیه یک عنصر است که یک جفت مبدأ-مقصد است.
• برای Maps JavaScript API، واحد سهمیه بارگیری نقشه است.
• برای کیت توسعه نرم‌افزار Maps برای Android و کیت توسعه نرم‌افزار Maps برای iOS، واحد سهمیه درخواست «نمای خیابان» یا بارگیری «تمام‌نما» است. بارگیری‌های نقشه بدون هزینه دردسترس است و سهمیه مصرف نمی‌کند.

برای دسترسی به صفحه «سهمیه‌های پلاتفرم Google Maps»:

1. صفحه Google Maps Platform را در کنسول Cloud باز کنید:

   به صفحه Google Maps Platform بروید

2. در منوِ سمت راست، سهمیه‌ها را انتخاب کنید.
3. یک API از فهرست کرکره‌ای API انتخاب کنید.

واحدهای سهمیه

این جدول واحد سهمیه را برای Google Maps Platform APIs نشان می‌دهد.

Google Maps Platform API	واحد سهمیه
Maps
کیت توسعه نرم‌افزار نقشه برای Android	‫۱ تمام‌نما
کیت توسعه نرم‌افزار نقشه برای iOS	‫۱ تمام‌نما
Map Tiles API	‫۱ درخواست
Maps Aerial View API	‫۱ درخواست
Maps Static API	‫۱ درخواست
Maps JavaScript API	۱ بار کردن نقشه
Street View Static API	‫۱ درخواست
Maps Embed API	۱ بار کردن نقشه
مسیرها
میانای برنامه‌سازی کاربردی مسیرها (محاسبه مسیرها)	‫۱ درخواست
میانای برنامه‌سازی کاربردی مسیرها (محاسبه ماتریس مسیر)	۱ عنصر (جفت مبدأ-مقصد)
Directions API (Legacy)	‫۱ درخواست
Distance Matrix API (Legacy)	۱ عنصر (جفت مبدأ-مقصد)
Roads API	‫۱ درخواست
Route Optimization API	‫۱ درخواست
کیت توسعه نرم‌افزار پیمایش برای Android	۱ مقصد
کیت توسعه نرم‌افزار پیمایش برای iOS	‫۱ مقصد
مکان‌ها
Places API	‫۱ درخواست
Places Aggregate API	‫۱ درخواست
میانای برنامه کاربردی برای اعتبارسنجی نشانی	‫۱ درخواست
Geocoding API	‫۱ درخواست
Geolocation API	‫۱ درخواست
Time Zone API	‫۱ درخواست
Maps Experience Agent Tools	‫۱ درخواست
محیط
Air Quality API (CurrentConditions و HeatmapTile)	‫۱ درخواست
Air Quality API (History)	1 صفحه
Pollen API	‫۱ درخواست
Solar API	‫۱ درخواست
Weather API	‫۱ درخواست

گزارش‌های صورت‌حساب

مشاهده گزارش صورت‌حساب

گزارش‌های صورت‌حساب برای استفاده شما از محصولات «پلاتفرم Google Maps» در کنسول Google Cloud دردسترس است. برای اطلاعات بیشتر، به صورت‌حساب مراجعه کنید.

برای دسترسی به گزارش‌های صورت‌حساب:

1. صفحه «انتخابگر پروژه» را در کنسول Cloud باز کنید:

   صفحه انتخابگر پروژه

2. پروژه‌ای را انتخاب کنید.
3. دکمه منو و سپس صدور صورت‌حساب را انتخاب کنید.
4. اگر چند حساب صورت‌حساب دارید، رفتن به حساب صورت‌حساب پیوندشده را انتخاب کنید تا صفحه نمای کلی برای حساب صورت‌حساب پیوندشده باز شود.
5. در منو سمت راست، گزارش‌ها را انتخاب کنید تا صفحه گزارش‌های صورت‌حساب برای حساب صورت‌حساب پیوندشده باز شود.

نحوه خواندن نمودار گزارش صورت‌حساب

گزارش‌های صورت‌حساب هزینه را درطول زمان به‌صورت نمودار خطی پشته‌ای ترسیم می‌کنند. نمای پیش‌فرض هزینه‌های خاص استفاده روزانه ماه جاری را که براساس پروژه (برای همه محصولات) گروه‌بندی شده است، ازجمله هرگونه اعتبار خاص استفاده اعمال‌شده، و همچنین کل هزینه پیش‌بینی‌شده برای کل ماه جاری را نمایش می‌دهد. هر خط در نمودار (و ردیف در جدول خلاصه) با پروژه مطابقت دارد و از بزرگ‌ترین به کوچک‌ترین براساس هزینه رتبه‌بندی شده است. درباره تفسیر نمودار گزارش صورت‌حساب بیشتر بدانید.

شکل ۱: گزارش صورت‌حساب که نمودار و جدول را بااستفاده از نمای پیش‌تنظیم پیش‌فرض نمایش می‌دهد.

نکته: مصرف و هزینه را براساس «واحد نگهداری موجودی» تحلیل کنید

برای درک دقیق‌تر جزئیات مدل قیمت‌گذاری پرداخت به اندازه استفاده و تأثیر آن بر پیاده‌سازی‌تان، میزان استفاده و هزینه را براساس شناسه کالا بررسی کنید.

شکل ۲: جدول صورت‌حساب که موارد سطری استفاده و هزینه را براساس SKU نمایش می‌دهد.

شکل ۳: فیلترهای گزارش صورت‌حساب.

برای تغییر نمای گزارش برای نمایش ردیف‌ها براساس SKU:

1. در پانل سمت چپ نمودار، فیلتر گروه براساس را ازهم باز کنید.
2. SKU را انتخاب کنید.

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

برای دسته‌بندی منبع استفاده‌تان علاوه‌بر محصول، گزارش‌های صورت‌حساب را براساس یکی از مقادیر فهرست‌شده گروه‌بندی کنید. سه کلید مربوط به میاناهای برنامه‌سازی کاربردی Google Maps Platform عبارت‌اند از goog-maps-api-key-suffix (چهار نویسه آخر کلید میانای برنامه‌سازی کاربردی)، goog-maps-platform-type (پلاتفرم: Android،‏ iOS،‏ JavaScript، یا وب‌سرویس)، و goog-maps-channel (مقدار عددی تنظیم‌شده کانال از پُرسمان میانای برنامه‌سازی کاربردی). اطلاعات بیشتر درباره فیلتر کردن و گروه‌بندی.

می‌توانید نمای نمودار را تغییر دهید تا اعتبارات مختص استفاده را با پاک کردن چارگوش انتخاب افزودن اعتبارات به هزینه در پانل سمت چپ کنار بگذارید.

پایش و محدود کردن مصرف

برای کمک به شما در برنامه‌ریزی بودجه و کنترل هزینه‌ها، می‌توانید کارهای زیر را انجام دهید:

• تنظیم بودجه

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

• محدود کردن API روزانه

  استفاده، برای مدیریت هزینه استفاده از میاناهای برنامه‌سازی کاربردی قابل‌صورت‌حساب. با تنظیم سقف برای درخواست‌ها در روز، می‌توانید هزینه‌تان را محدود کنید. از معادله‌ای برای تعیین سقف روزانه خود بسته به میزان هزینه‌ای که می‌خواهید بپردازید استفاده کنید. برای مثال: (هزینه ماهانه / قیمت هر SKU) / ۳۰ = سقف درخواست‌ها در روز (برای یک API).

  توجه: پیاده‌سازی شما ممکن است از چندین API قابل‌صورت‌حساب استفاده کند که به‌نوبه خود از چندین SKU استفاده می‌کنند، بنابراین معادله خود را درصورت نیاز تنظیم کنید.
  مقدار استفاده ماهانه رایگانی را که هر میانای برنامه‌سازی کاربردی ارائه می‌دهد و در فهرست قیمت‌گذاری نشان داده شده است در محاسباتتان لحاظ کنید.

ردیابی مصرف برای هر کانال

برای ردیابی استفاده‌تان بااستفاده از کانال‌های عددی، باید پارامتر «کانال» را به درخواست‌های میانای برنامه‌سازی کاربردی‌تان اضافه کنید. تنها مقادیر پذیرفتنی کانال، اعداد ۰ تا ۹۹۹ است. در اینجا چند مثال آورده شده است:

• Geocoding Web Service API

  https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY&channel=1

• Maps JavaScript API

  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&channel=2&callback=initMap"
  async defer></script>

استفاده از کانال را مستقیماً در «گزارش صورت‌حساب» خود پایش کنید. استفاده از کانال زیر برچسب‌ها به‌عنوان کلید goog-maps-channel است.

توجه: داده‌های کانال برای «کیت توسعه نرم‌افزار Google Maps برای Android»، «کیت توسعه نرم‌افزار Google Maps برای iOS»، «Places API (جدید)»، «کیت توسعه نرم‌افزار Places برای Android»، «کیت توسعه نرم‌افزار Places برای iOS»، «کیت توسعه نرم‌افزار پیمایش برای Android»، «کیت توسعه نرم‌افزار پیمایش برای iOS»، ‏Places Aggregate API، ‏Address Validation API، ‏Aerial View API، ‏Air Quality API، ‏Map Tiles API، Maps Datasets API، ‏Roads API، ‏Routes API، Pollen API، ‏Solar API، Route Optimization API، و Weather API دردسترس نیست.

شکل ۴: فیلتر کردن براساس SKU و کانال‌ها

برای فیلتر کردن گزارش صورت‌حساب براساس SKU و کانال

1. از فیلتر گروه‌بندی براساس شناسه کالا استفاده کنید.
2. نشانگر برچسب‌ها را انتخاب کنید.
3. از منو کرکره‌ای کلید، goog-maps-channel را انتخاب کنید.
4. از منوِ کرکره‌ای مقدار، کانال‌های عددی موردنظرتان را برای فیلتر کردن انتخاب کنید.

براساس کلید برچسب goog-maps-channel گروه‌بندی کنید تا هزینه تولیدشده توسط هر کانال را ببینید.

پس‌از پیاده‌سازی داده‌های استفاده از کانال در درخواست‌هایتان، ممکن است تأخیر کوتاهی (تا ۲۴ ساعت) وجود داشته باشد تا داده‌ها در گزارش صورت‌حساب شما منعکس شود.

صادر کردن داده‌های صورت‌حساب با BigQuery

همچنین می‌توانید داده‌های صورت‌حساب خود را به BigQuery صادر کنید.

از BigQuery Export برای صادر کردن داده‌های دقیق Cloud Billing (مانند داده‌های استفاده و برآورد هزینه) به‌طور خودکار درطول روز به مجموعه‌داده BigQuery که مشخص می‌کنید استفاده کنید. سپس می‌توانید برای تجزیه‌وتحلیل دقیق، از BigQuery به داده‌های صورت‌حساب خود دسترسی پیدا کنید. این کار لایه اضافی از جزئیات را برای درک منبع استفاده شما از «پلاتفرم Google Maps» فراهم می‌کند.

اگر می‌خواهید با صادر کردن BigQuery و پُرسمان داده‌ها شروع کنید، می‌توانید پُرسمان نمونه زیر را امتحان کنید. پیش‌از اجرای این پُرسمان، باید:

• صدور صورت‌حساب و صادر کردن صورت‌حساب BigQuery را در حسابتان فعال کنید.
• قالب جدول PROJECT_ID.DATASET_NAME.gcp_billing_exportv1BILLING_ACCOUNT_ID است که در آن:
• PROJECT_ID شناسه پروژه واقعی شما است (برای مثال، «my-project-123456»).
• DATASET_NAME نام مجموعه داده‌ای است که ایجاد کرده‌اید (مثلاً «SampleDataSet»).
• ‫BILLING_ACCOUNT_ID مرجعی از «شناسه حساب صورت‌حساب» شما است، که پیشوند «gcp_billing_exportv1» دارد و خط تیره‌ها (-) به زیرخط (_) تغییر کرده است. برای مثال، شناسه حساب صورت‌حساب 123456-7890AB-CDEF01 به gcp_billing_export_v1_123456_789AB_CDEF01 تبدیل می‌شود.

توجه: وقتی DataSet جدیدی ایجاد می‌کنید، فوراً در میانای کاربری نشان داده می‌شود، اما «جدول» برای پُرسمان هنوز نشان داده نمی‌شود. این جدول پس‌از چند ساعت به‌طور خودکار تولید خواهد شد. سپس حدود ۲۴ ساعت طول می‌کشد تا داده‌هایتان را ببینید. مجموعه داده BigQuery شما فقط داده‌های استفاده و هزینه را که از تاریخ راه‌اندازی صادر کردن صورت‌حساب و پس‌از آن ایجاد شده است منعکس می‌کند. به عبارت دیگر، داده‌های صورت‌حساب عطف به ماسبق اضافه نمی‌شوند، بنابراین داده‌های صورت‌حساب را از قبل‌از فعال کردن صادر کردن BigQuery نخواهید دید.

  #standardSQL
  SELECT   Date(usage_start_time, "America/Los_Angeles") AS billing_day,
           invoice.month                                 AS invoice_month,
           service.description                           AS service,
           sku.description                               AS sku,
           (
                  SELECT l.value
                  FROM   Unnest(labels) AS l
                  WHERE  l.KEY = 'goog-maps-channel' ) AS goog_maps_channel,
           Round(Sum(usage.amount), 2)                 AS usage_amount,
           usage.unit                                  AS usage_unit,
           Round(Sum(cost), 2)                         AS cost,
           cost_type,
           currency
  FROM     PROJECT_ID.DATASET_NAME.gcp_billing_export_v1_BILLING_ACCOUNT_ID
  WHERE    invoice.month = '202002' -- Change the invoice month with the same format as the example.
  GROUP BY billing_day,
           invoice_month,
           service,
           sku,
           goog_maps_channel,
           usage_unit,
           cost_type,
           currency
  ORDER BY billing_day,
           service,
           sku
  

منابع مربوط

Cloud Billing:

• ایجاد، اصلاح، یا بستن حساب Cloud Billing
• اصلاح تنظیمات صورت‌حساب پروژه
• مشاهده گزارش‌های صورت‌حساب و روندهای هزینه
• تنظیم بودجه و هشدارهای بودجه
• محدود کردن استفاده از API

Google Maps Platform:

• صورت‌حساب پلاتفرم Google Maps
• راهنمای بهینه‌سازی
• روال‌های مطلوب کلید میانای برنامه‌سازی کاربردی

وضعیت پاسخ و گزارش‌ها

جدول زیر نگاشت بین وضعیت Maps API، کد پاسخ HTTP برگردانده‌شده در پاسخ‌های Maps API، و کلاس کد پاسخ HTTP در «گزارش استفاده» را نشان می‌دهد و مشخص می‌کند که آیا درخواست مربوطه در گزارش‌های «استفاده»، «سهمیه»، و «صورت‌حساب» نمایش داده می‌شود یا نه.

توجه: به دلایل تاریخی، کد پاسخ HTTP برگردانده‌شده در پاسخ به درخواست‌های Google Maps Platform API می‌تواند با کد پاسخ HTTP در گزارش‌های «استفاده» (سنجه‌های Google Maps Platform) متفاوت باشد. سنجه‌های «گزارش‌های استفاده» از مجموعه‌ای از مقادیر کد پاسخ استفاده می‌کنند که با مقادیر استفاده‌شده در میاناهای برنامه‌سازی کاربردی جدیدتر سازگار است. این کار مشاهده‌پذیری استفاده از میاناهای برنامه‌سازی کاربردی را در سنجه‌های پلاتفرم Google Maps و پایش پلاتفرم Google Maps بهبود می‌بخشد.

«گزارش استفاده» در سنجه‌های پلاتفرم Google Maps

جزئیات HTTP response code class را ارائه می‌دهد. اگر به سطح بالاتری از جزئیات نیاز دارید، کدهای وضعیت پاسخ را ببینید

در پایش استفاده از «پلاتفرم Google Maps» دردسترس است.

کدهای پاسخ موجود در پاسخ‌های Maps API		در «گزارش استفاده» دردسترس است	گزارش‌شده به
وضعیت Maps API	کد پاسخ HTTP	کلاس کد پاسخ HTTP	کاربرد	سهمیه	صورت‌حساب
تأیید	200, 204, 302	‫2xx،‏ 3xx	بله	بله	بله
DATA_NOT_AVAILABLE, NOT_FOUND, ZERO_RESULTS	‫۲۰۰، ۴۰۴	‫4xx^۱	بله	بله	بله
INVALID_REQUEST (invalid parameter value), MAX_ROUTE_LENGTH_EXCEEDED, MAX_WAYPOINTS_EXCEEDED, etc.	۲۰۰، ۴۰۰	4xx	بله	بله	بله
INVALID_REQUEST (پارامتر نامعتبر/ مفقود، خطای تجزیه درخواست)	۲۰۰، ۴۰۰	4xx	بله	نه	نه
REQUEST_DENIED	۲۰۰، ۴۰۰، ۴۰۳	‫4xx^۱	بله	نه	نه
OVER_DAILY_LIMIT, OVER_QUERY_LIMIT, RESOURCE_EXHAUSTED, dailyLimitExceeded, rateLimitExceeded, userRateLimitExceeded	‫۲۰۰، ۴۰۳، ۴۲۹	‫4xx^۱	بله	نه	نه
UNKNOWN_ERROR	‫۲۰۰، ۵۰۰، ۵۰۳	‫5xx^۱	بله	بله	نه
^۱ برای بهبود سازگاری گزارش کد خطا، میاناهای برنامه‌سازی کاربردی Google Maps Platform در حال انتقال هستند: ۱) از کلاس کد پاسخ HTTP‏ 2xx به 4xx برای وضعیت‌های Maps API: ‏DATA_NOT_AVAILABLE، NOT_FOUND، ZERO_RESULTS - وضعیت، ۲) از کلاس کد پاسخ HTTP‏ 2xx به 4xx برای وضعیت‌های Maps API: ‏REQUEST_DENIED، OVER_DAILY_LIMIT، OVER_QUERY_LIMIT، dailyLimitExceeded، rateLimitExceeded، userRateLimitExceeded، ۳) از کلاس کد پاسخ HTTP‏ 2xx به 5xx برای وضعیت Maps API: ‏UNKNOWN_ERROR. می‌توانید هر دو کد پاسخ را درطول دوره انتقال ببینید. کدهای پاسخ برگردانده‌شده در پاسخ‌های Maps API تغییر نمی‌کنند. با بررسی اینکه دقیقاً کدام کد پاسخ در کاوشگر سنجه‌ها افزایش می‌یابد، تأیید کنید که افزایش در 4xx و/یا 5xx در سنجه‌های پلاتفرم Google Maps به این انتقال مربوط است (درباره استفاده از Google Cloud Monitoring برای «پلاتفرم Google Maps» بیشتر بدانید).