نمای کلی
برای شروع مراحل زیر را دنبال کنید:
- بررسی استفاده فعلی از شناسه کارخواه
- آماده‌سازی کلیدهای میانای برنامه‌سازی کاربردی
- بررسی تنظیمات سهمیه
- به‌روزرسانی کد
- پایش ترافیک شناسه کارخواه
- توقف موقت شناسه کارخواه
- فعال‌سازی مجدد موقت شناسه کارخواه به‌صورت سلف سرویس
بررسی مصرف شناسه کارخواه فعلی
قبل‌از شروع فرایند انتقال، موارد زیر را فهرست کنید:
- «سرویس‌های پلاتفرم Maps» که با شناسه کارخواهتان از آن‌ها استفاده می‌کنید.
- برنامه‌ها، سایت‌ها، یا سیستم‌هایی که با آن‌ها از شناسه کارخواه خود استفاده می‌کنید.
Google در مه ۲۰۲۵ ایمیل اعلانی درباره منسوخ شدن شناسه کارخواه به مشتریان تحت‌تأثیر ارسال کرد. این اطلاعات را در ایمیل اعلان نیز می‌توانید پیدا کنید.
در Cloud Console، می‌توانید جدیدترین وضعیت استفاده از «شناسه مشتری» خود را در صفحه سنجه‌های Google Maps بررسی کنید
برای فهرست «سرویس‌های پلاتفرم Maps»:
- صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
- استفاده‌تان را با تنظیمات زیر فیلتر کنید:
- اعتبارنامه: فقط «project_number:<شناسه عددی>» را انتخاب کنید.
- فیلتر زیر را تنظیم کنید.
- گروه‌بندی براساس: میانای برنامه‌سازی کاربردی
برای راهنمایی‌های برنامه‌ها، سایت‌ها، یا سیستم‌ها:
Cloud Console جزئیات برنامه‌ها، سایت‌ها، یا سیستم‌هایتان را نشان نمی‌دهد. اما می‌توانید نشانه‌هایی از منابع ترافیک شناسه کارخواه خود را پیدا کنید. این مراحل را دنبال کنید:
- صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
- یکی از سرویس‌های Maps Platform را از منو کرکره‌ای انتخاب کنید.
- استفاده‌تان را با تنظیمات زیر فیلتر کنید:
- اعتبارنامه: فقط «project_number:<شناسه عددی>» را انتخاب کنید.
- فیلتر زیر را تنظیم کنید.
- گروه‌بندی براساس: پلاتفرم، یا دامنه
- از مرحله ۲ برای هر سرویس Maps Platform که باید ترافیک آن را بررسی کنید تکرار کنید.
آماده‌سازی کلیدهای میانای برنامه‌سازی کاربردی
همه شناسه‌های کارخواه با پروژه Google Cloud مرتبط هستند و استفاده از کلید میانای برنامه‌سازی کاربردی از آن پروژه به شما امکان می‌دهد به همان ویژگی‌هایی دسترسی داشته باشید که قبلاً با شناسه کارخواهتان به آن‌ها دسترسی داشتید. توصیه می‌کنیم به پروژه مرتبط منتقل شوید تا با مشکلاتی مثل سهمیه یا ویژگی‌های ازدست‌رفته مواجه نشوید.
- «پروژه ابری» را که شناسه کارخواه شما به آن پیوند شده است پیدا کنید:
- مطمئن شوید «پروژه Cloud» شما به «حساب صورت‌حساب» باز پیوند شده باشد.
- برای انتقال شناسه مشتری، کلید میانای برنامه‌سازی کاربردی جدیدی ایجاد کنید.
- می‌توانید از هر کلید میانای برنامه‌سازی کاربردی موجود در «پروژه ابری» دوباره استفاده کنید.
- می‌توانید از چند کلید API از یک «پروژه ابری» استفاده کنید، برای مثال، برای جدا کردن ترافیک هر سرویس Maps Platform، یا برای جدا کردن ترافیک پلاتفرم‌های مختلف (مرورگر، برنامه تلفن همراه، و غیره). برای روال‌های مطلوب مدیریت کلید میانای برنامه‌سازی کاربردی، به راهنمای امنیتی مراجعه کنید.
ایمن کردن کلید میانای API
حتماً کلید میانای API خود را ایمن کنید تا از دسترسی غیرمجاز به کلیدتان جلوگیری شود.
- محدودیت برنامه برای کلید میانای برنامه‌سازی کاربردی‌تان تنظیم کنید (مثلاً وب‌سایت‌ها، نشانی‌های IP، برنامه‌های Android، یا برنامه‌های iOS).
- محدودیت‌های میانای برنامه‌سازی کاربردی را برای کلید میانای برنامه‌سازی کاربردی‌تان تنظیم کنید.
برای جزئیات بیشتر، راهنمای امنیتی Google Maps Platform را ببینید.
برای Maps JavaScript API، Maps Static API، و Street View Static API، می‌توانید ارجاع‌دهنده‌های مورداعتماد را در شناسه کارخواه خود به محدودیت‌های کلید میانای برنامه‌سازی کاربردی منتقل کنید. می‌توانید فهرست ارجاع‌دهندگان مورداعتماد را در Cloud Console پیدا کنید.
مرور تنظیمات سهمیه
مطمئن شوید تنظیمات سهمیه موردانتظار را در «پروژه ابری» خود دارید. فقط درصورتی باید این کار را انجام دهید که سرویس‌های سمت کارخواه Maps JavaScript API را از شناسه کارخواه فراخوانی می‌کنید. می‌توانید تنظیمات سهمیه‌تان را در صفحه سهمیه‌های Google Maps بررسی و اصلاح کنید.
درباره گزارش‌های سهمیه بیشتر بدانید
افزایش سهمیه برای سرویس‌های سمت کارخواه Maps JavaScript API
اگر از سرویس‌های زیر در Maps JavaScript API استفاده می‌کنید، پس‌از انتقال کلید میانای برنامه‌سازی کاربردی، افزایش استفاده از سهمیه را خواهید دید.
پیکربندی سهمیه فعلی، استفاده فعلی، و حدود سهمیه خود را براین‌اساس تنظیم کنید.
- بررسی کنید که آیا از سرویس‌های سمت کارخواه Maps JavaScript API با شناسه کارخواه استفاده می‌کنید یا نه.
- صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
- استفاده‌تان را با تنظیمات زیر فیلتر کنید:
- گروه‌بندی براساس: روش میانای برنامه‌سازی کاربردی
- اعتبارنامه: فقط «project_number:<شناسه عددی>» را انتخاب کنید.
- سپس، فهرستی از نام‌های «روش» را با ترافیک آن در نمودار «ترافیک براساس روش میانای برنامه‌سازی کاربردی» خواهید دید.
روش میانای برنامه‌سازی کاربردی |
سرویس سمت کارخواه |
سرویس برای تنظیم سهمیه |
google.routes.Directions.Javascript |
سرویس مسیرها |
Directions API |
google.routes.DistanceMatrix.Javascript |
Distance Matrix Service |
Distance Matrix API |
google.maps.Elevation.Javascript |
سرویس ارتفاع |
Elevation API |
google.places.Geocoding.Javascript |
Geocoding Service |
Geocoding API |
google.places.*.Javascript، به‌جز google.places.Geocoding.Javascript |
کتابخانه جاها |
Places API |
- اگر از آن روش‌های میانای برنامه‌سازی کاربردی استفاده نمی‌کنید، لازم نیست نگران تنظیمات سهمیه باشید، زیرا ترافیک شناسه مشتری شما ازقبل سهمیه پروژه شما را مصرف می‌کند.
- برآورد استفاده از سهمیه شناسه کارخواه
- برای هریک از سرویس‌ها، هم دانه‌بندی «در ثانیه» و هم «در روز» را بررسی کنید.
- نمودار «در ثانیه»: برای نیازهای «سهمیه در دقیقه» اضافی، اوج ترافیک را در ۶۰ ضرب کنید.
- نمودار «در روز»: اوج ترافیک باید «سهمیه اضافی در روز» موردنیاز باشد.
- سهمیه‌تان را در سرویس‌های مربوطه Maps Platform تنظیم کنید
- براساس نام روشی که در مرحله ۱ پیدا می‌کنید، سهمیه را در سرویس‌های مربوطه تنظیم کنید.
به‌روزرسانی کد
جایگزین کردن پارامتر مشتری با پارامتر کلید
اعتبارنامه‌های اصالت‌سنجی را از URL&client={value} به
URL&key={value} در تماس‌های میانای برنامه‌سازی کاربردی GMP خروجی به‌روز کنید. اگر برنامه‌هایتان از HTTP برای دسترسی به سرویس‌های GMP استفاده می‌کنند، آن‌ها را به‌روز کنید تا از HTTPS استفاده کنند.
به‌روزرسانی پارامتر کانال برای گزارش‌دهی
می‌توانید با مشخص کردن پارامتر کانال برای درخواست‌های میانای برنامه‌سازی کاربردی، استفاده‌تان را براساس کانال‌ها ردیابی کنید. کلیدهای میانای برنامه‌سازی کاربردی فقط از مقادیر عددی برای پارامتر کانال پشتیبانی می‌کنند. اگر از «شناسه مشتری» با مقادیر غیرعددی برای پارامتر کانال استفاده می‌کنید، آن را به مقادیر پشتیبانی‌شده عددی به‌روز کنید.
برای اطلاعات بیشتر، گزارش‌دهی Google Maps Platform را ببینید.
برداشتن پارامتر امضا برای سرویس‌های وب
برای میاناهای برنامه‌سازی کاربردی Web Service زیر، وقتی با کلید میانای برنامه‌سازی کاربردی به آن‌ها دسترسی پیدا می‌کنید، پارامتر امضا لازم نیست. فقط پارامتر امضا را از درخواست‌های API خود بردارید.
- Directions API (Legacy)
- Distance Matrix API (Legacy)
- Geocoding API
- Elevation API
- Time Zone API
برای اطلاعات بیشتر، نمای کلی طرح Premium را ببینید.
رمز امضا برای میاناهای برنامه‌سازی کاربردی تصاویر
Maps Static API و Street View Static API همچنان به پارامتر امضا نیاز دارند. آن‌ها تعداد کمی از درخواست‌های بدون امضا را برای اهداف آزمایشی می‌پذیرند، اما وقتی به آستانه تولید شما برسد، با شکست مواجه می‌شوند. رمز امضا را از رمز مربوط به شناسه کارخواه به رمز مربوط به کلید میانای API تغییر دهید. می‌توانید از همان الگوریتم امضا استفاده کنید، اما باید از کلید خصوصی امضای دیگری استفاده کنید. برای کسب اطلاعات بیشتر، استفاده از امضای دیجیتال را ببینید.
ترافیک شناسه کارخواه خود را پایش کنید
پس‌از استقرار، بااستفاده از داشبوردهای Cloud Console تأیید کنید که ترافیکتان باموفقیت منتقل شده است. شاهد کاهش ترافیک شناسه مشتری خود خواهید بود که در داشبورد با قالب «project_number:123456» هنگام گروه‌بندی براساس اطلاعات کاربری نشان داده می‌شود.
موقتاً متوقف کردن شناسه کارخواه
اکیداً به توسعه‌دهندگان توصیه می‌کنیم شناسه‌های کارخواه را پس‌از انتقال موقتاً متوقف کنند. این کار برای محافظت از اعتبارنامه‌های شما دربرابر ترافیک ناخواسته و تأیید این موضوع است که هرگونه استفاده باقی‌مانده از شناسه مشتری شما حیاتی نیست (مثلاً آزمایش، حافظه‌های پنهان، ربات‌ها، …) و می‌تواند بدون تأثیر بر کسب‌وکار، خطا برگرداند. می‌توانید شناسه کارخواهتان را در «کنسول Cloud» موقتاً متوقف کنید. برای جزئیات بیشتر، نمای کلی اصالت‌سنجی طرح Premium را ببینید.
فعال‌سازی مجدد موقت شناسه کارخواه به‌صورت سلف سرویس
ازآنجایی‌که شناسه‌های کارخواه Google Maps Platform در مه ۲۰۲۶ وارد دوره منسوخ شدن مرحله‌ای شده‌اند، دردسترس بودن سرویس دیگر تضمین نمی‌شود. دسترسی به‌صورت دوره‌ای به‌عنوان بخشی از فرایند زمان‌بندی‌شده پایان سرویس محدود خواهد شد. درحالی‌که سرویس معمولاً ظرف چند ساعت به‌طور خودکار بازیابی می‌شود، اگر بازیابی فوری لازم باشد، می‌توانید دسترسی را به‌طور دستی دوباره فعال کنید.
برای بازیابی فوری دسترسی، می‌توانید ازطریق «کنسول Google Cloud» فعال‌سازی مجدد خودیاری را انجام دهید:
- به صفحه اطلاعات کاربری پلاتفرم Google Maps بروید.
- «پروژه Cloud» خاصی را که به «شناسه کارخواه» شما پیوند شده است پیدا کنید.
- برای بازیابی سرویس، روی نماد لغو توقف در منتهی‌الیه سمت چپ ورودی کلیک کنید.
اگر نمی‌توانید به‌سرعت به کلیدهای API مهاجرت کنید و می‌خواهید موقتاً از وقفه‌های بیشتر معاف شوید، لطفاً با جزئیات زیر با تیم پشتیبانی Google Maps Platform تماس بگیرید:
- شناسه کارخواه
- مورد استفاده خاص
- تاریخ انتقال هدف
- ارزیابی تأثیر کسب‌وکار
گزارش استفاده از شناسه کارخواه - از گزارش‌های صورت‌حساب
بررسی گزارش‌های «صورت‌حساب» به‌جای «سنجه‌های پروژه» می‌تواند برای کاربرانی که به سنجه‌های پروژه دسترسی ندارند مفید باشد—برای مثال، سرپرستان صورت‌حساب (به‌ویژه «شرکای Maps Platform»). درحالی‌که «گزارش‌های صورت‌حساب» ۱ تا ۲ روز تأخیر دارند، این مزیت را دارند که بیش‌از ۳۰ روز اطلاعات آماری استفاده و هزینه را نشان می‌دهند.
با دنبال کردن این مراحل می‌توانید استفاده از «شناسه کارخواه» را ازطریق Google Cloud Console پایش کنید:
- به صفحه صورت‌حساب > گزارش‌ها در «کنسول Google Cloud» بروید.
- (اختیاری، فقط برای شرکا) فیلتری را برای انتخاب حساب فرعی صورت‌حساب موردنظر اعمال کنید.
- داده‌های گزارش را براساس کلید برچسب
goog-maps-api-key-suffixگروه‌بندی کنید. این برچسب نویسه‌های پایانی کلید میانای برنامه‌سازی کاربردی را نمایش می‌دهد. - ترافیک «شناسه کارخواه» را با جستجوی ورودی‌هایی که برچسب
goog-maps-api-key-suffixدر آن‌ها وجود ندارد یا خالی است شناسایی کنید، زیرا این برچسب برای درخواست‌های «شناسه کارخواه» پر نمی‌شود. - از شناسه‌های یکتای کالایی که قرار نیست با درخواست‌های API مرتبط شوند، صرف‌نظر کنید—برای مثال، شناسه‌های یکتای کالای اشتراک.
عیب‌یابی
چگونه می‌توانیم ببینیم که درخواست ما ناموفق است یا نه؟
می‌توانید آمار خطای خود را در نمودارهای کد پاسخ بررسی کنید
خطای ApiNotActivatedMapError یا REQUEST_DENIED
اگر سرویس را در «پروژه ابری» خود فعال نکرده باشید، خطای ApiNotActivatedMapError یا REQUEST_DENIED را خواهید دید. دستورالعمل‌ها را برای
فعال کردن سرویس دنبال کنید.
RefererNotAllowedMapError خطا
اگر دامنه منبع شما به کلید میانای برنامه‌سازی کاربردی‌تان اضافه نشده باشد، خطای RefererNotAllowedMapError را خواهید دید. بخش «ایمن کردن کلید میانای برنامه‌سازی کاربردی» را بررسی کنید و دامنه‌تان را به کلید میانای برنامه‌سازی کاربردی اضافه کنید.
خطای OverQuotaMapError یا OVER_QUERY_LIMIT
اگر سهمیه پیکربندی‌شده شما برای پوشش ترافیکتان کافی نباشد، OverQuotaMapError یا OVER_QUERY_LIMIT را خواهید دید. بخش «بررسی تنظیمات سهمیه» را بررسی کنید و سهمیه‌تان را براساس آن تنظیم کنید.
خطای «درخواست‌ها به این API باید ازطریق SSL باشد»
اگر پیام خطای زیر را دریافت کردید، درخواست‌های API خود را از «http://» به «https://» به‌روز کنید.
{
"error_message" : "Requests to this API must be over SSL. Load the API with
\"https://\" instead of \"http://\".",
"results" : [],
"status" : "REQUEST_DENIED"
}