راهنمای انتقال شناسه کارخواه

نمای کلی

مهم: به‌منظور افزایش امنیت و قابلیت اطمینان اصالت‌سنجی، شناسه‌های کارخواه «پلاتفرم Maps» از ۲۶ مه ۲۰۲۵ منسوخ شده‌اند و دیگر نمی‌توان از آن‌ها پس‌از ۳۱ مه ۲۰۲۶ استفاده کرد.
به‌جای استفاده از شناسه کارخواه، باید از اطلاعات کاربری «کلید میانای برنامه‌سازی کاربردی» برای اصالت‌سنجی ترافیک سرویس Google Maps API استفاده کنید. این راهنما نحوه انتقال از استفاده از شناسه‌های کارخواه به استفاده از کلیدهای API را نشان می‌دهد.

برای شروع مراحل زیر را دنبال کنید:

1. بررسی استفاده از شناسه کارخواه کنونی
2. آماده‌سازی کلیدهای API
3. مرور تنظیمات سهمیه
4. به‌روزرسانی کد
5. پایش ترافیک شناسه کارخواه
6. توقف موقت شناسه کارخواه
7. فعال‌سازی موقت خودکار شناسه کارخواه

بررسی استفاده از شناسه کارخواه فعلی

قبل‌از شروع فرایند انتقال، موارد زیر را فهرست کنید:

• «سرویس‌های پلاتفرم Maps» که با شناسه کارخواهتان از آن‌ها استفاده می‌کنید.
• برنامه‌ها، سایت‌ها، یا سیستم‌هایی که با آن‌ها از شناسه کارخواه خود استفاده می‌کنید.

Google در مه ۲۰۲۵ ایمیل اعلانی درباره منسوخ شدن شناسه کارخواه به مشتریان تحت‌تأثیر ارسال کرد. این اطلاعات را در ایمیل اعلان نیز می‌توانید پیدا کنید.

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

برای فهرست «سرویس‌های پلاتفرم Maps»:

1. صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
2. استفاده‌تان را با تنظیمات زیر فیلتر کنید:
   • اطلاعات اعتباری: فقط «project_number:<numerical identifier>‎» را انتخاب کنید.
3. فیلتر زیر را تنظیم کنید.
   • گروه‌بندی‌شده براساس: میانای برنامه‌سازی کاربردی

برای نکات برنامه‌ها، سایت‌ها، یا سیستم‌ها:

Cloud Console جزئیات برنامه‌ها، سایت‌ها، یا سیستم‌هایتان را نشان نمی‌دهد. اما می‌توانید نشانه‌هایی از منابع ترافیک «شناسه کارخواه» خود پیدا کنید. این مراحل را دنبال کنید:

1. صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
2. یکی از سرویس‌های «پلاتفرم Maps» را از منو کرکره‌ای انتخاب کنید.
3. استفاده‌تان را با تنظیمات زیر فیلتر کنید:
   • اطلاعات اعتباری: فقط «project_number:<numerical identifier>‎» را انتخاب کنید.
4. فیلتر زیر را تنظیم کنید.
   • گروه‌بندی براساس: پلاتفرم، یا دامنه
5. مراحل را از مرحله ۲ برای هر سرویس Maps Platform که می‌خواهید ترافیک آن را بررسی کنید تکرار کنید.

آماده کردن کلیدهای میانای برنامه‌سازی کاربردی

همه شناسه‌های کارخواه با پروژه Google Cloud مرتبط هستند و استفاده از کلید API از آن پروژه به شما امکان دسترسی به همان ویژگی‌هایی را می‌دهد که قبلاً با شناسه کارخواه خود به آن‌ها دسترسی داشتید. توصیه می‌کنیم به پروژه مرتبط انتقال دهید تا با مشکلات سهمیه یا ویژگی‌های ازدست‌رفته مواجه نشوید.

1. «پروژه Cloud» را که شناسه کارخواهتان به آن پیوند شده است پیدا کنید:
   • پرسشگان انتقال پورتال
2. مطمئن شوید «پروژه Cloud» شما به «حساب صورت‌حساب» باز پیوند شده باشد.
3. برای انتقال شناسه کارخواه، کلید میانای API جدیدی ایجاد کنید.
   • می‌توانید از هر کلید API موجود در «پروژه ابری» استفاده مجدد کنید.
   • می‌توانید از چند کلید میانای برنامه‌سازی کاربردی از یک «پروژه ابری» استفاده کنید، برای مثال، برای جدا کردن ترافیک هر سرویس Maps Platform، یا برای جدا کردن ترافیک پلاتفرم‌های مختلف (مرورگر، برنامه تلفن همراه، و غیره). برای روال‌های مطلوب مدیریت کلید API، به راهنمای امنیتی مراجعه کنید.

ایمن کردن کلید میانای برنامه‌سازی کاربردی

برای محافظت از کلیدتان دربرابر دسترسی غیرمجاز، حتماً کلید میانای برنامه‌سازی کاربردی‌تان را ایمن کنید.

• برای کلید API خود محدودیت برنامه تنظیم کنید (برای نمونه، وب‌سایت‌ها، نشانی‌های IP، برنامه‌های Android، یا برنامه‌های iOS).
• محدودیت‌های میانای برنامه‌سازی کاربردی را برای کلید میانای برنامه‌سازی کاربردی خود تنظیم کنید.

برای جزئیات بیشتر، راهنمای امنیتی «پلاتفرم Google Maps» را ببینید.

برای Maps JavaScript API،‏ Maps Static API، و Street View Static API، می‌توانید ارجاع‌دهنده‌های مورداعتماد را در شناسه کارخواه خود به محدودیت‌های کلید میانای برنامه‌سازی کاربردی منتقل کنید. می‌توانید فهرست ارجاع‌دهندگان مورداعتماد را در «کنسول Cloud» پیدا کنید.

تنظیمات سهمیه را مرور کنید

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

درباره گزارش‌های سهمیه بیشتر بدانید

افزایش سهمیه برای خدمات سمت مشتری «میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps»

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

اگر از سرویس‌های زیر در «میانای برنامه کاربردی جاوا اسکریپت Maps» استفاده می‌کنید، پس‌از انتقال کلید API، افزایش استفاده از سهمیه را خواهید دید.

پیکربندی سهمیه فعلی، استفاده فعلی، و حدود سهمیه خود را براساس آن تنظیم کنید.

1. بررسی کنید که آیا از سرویس‌های سمت کارخواه «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» با شناسه کارخواه استفاده می‌کنید یا نه.
   • صفحه سنجه‌ها را در «کنسول Cloud» باز کنید.
   • استفاده‌تان را با تنظیمات زیر فیلتر کنید:
     • گروه‌بندی براساس: روش میانای برنامه‌سازی کاربردی
     • اطلاعات اعتباری: فقط «project_number:<numerical identifier>‎» را انتخاب کنید.
   • سپس، فهرستی از نام‌های «روش» را با ترافیک آن در نمودار «ترافیک براساس روش API» خواهید دید.

روش میانای برنامه‌سازی کاربردی	خدمات سمت کارخواه	سرویس برای تنظیم سهمیه
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

• اگر از آن روش‌های API استفاده نمی‌کنید، لازم نیست نگران تنظیمات سهمیه باشید، زیرا ترافیک شناسه کارخواه شما ازقبل سهمیه پروژه شما را مصرف می‌کند.
• برآورد استفاده از سهمیه شناسه کارخواه
  • برای هریک از سرویس‌ها، هم دانه به ثانیه و هم دانه به روز را بررسی کنید.
  • گراف «در ثانیه»: ترافیک اوج را در ۶۰ ضرب کنید تا نیازهای اضافی «سهمیه در دقیقه» را به‌دست آورید.
  • گراف «در روز»: ترافیک اوج باید «سهمیه اضافی در روز» موردنیاز باشد.
• سهمیه خود را در سرویس‌های مربوط به «پلاتفرم Maps» تنظیم کنید
  • براساس نام روشی که در «مرحله ۱» پیدا می‌کنید، سهمیه را در سرویس‌های مربوطه اصلاح کنید.

به‌روزرسانی کد

جایگزین کردن پارامتر مشتری با پارامتر کلید

اعتبارنامه‌های اصالت‌سنجی را از URL&client={value} به URL&key={value} در تماس‌های میانای برنامه‌سازی کاربردی GMP خروجی به‌روز کنید. اگر برنامه‌هایتان برای دسترسی به خدمات GMP از HTTP استفاده می‌کنند، آن‌ها را به‌روز کنید تا از HTTPS استفاده کنند.

به‌روزرسانی پارامتر کانال برای گزارش‌دهی

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

برای اطلاعات بیشتر، گزارش‌دهی پلاتفرم Google Maps را ببینید.

برداشتن پارامتر امضا برای خدمات وب

برای «میاناهای برنامه‌سازی کاربردی سرویس وب» زیر، وقتی با کلید میانای برنامه‌سازی کاربردی به آن‌ها دسترسی پیدا می‌کنید، پارامتر امضا لازم نیست. فقط پارامتر امضا را از درخواست‌های API خود بردارید.

• Directions API (قدیمی)
• ‫Distance Matrix API (قدیمی)
• 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» در ماه مه ۲۰۲۶ وارد دوره منسوخ شدن تدریجی شده‌اند، دردسترس بودن سرویس دیگر تضمین‌شده نیست. دسترسی به‌عنوان بخشی از فرایند پایان سرویس زمان‌بندی‌شده به‌صورت دوره‌ای محدود خواهد شد. اگرچه سرویس معمولاً ظرف چند ساعت به‌طور خودکار بازیابی می‌شود، درصورت نیاز به بازیابی فوری می‌توانید دسترسی را به‌صورت دستی فعال کنید.

برای بازیابی فوری دسترسی، می‌توانید ازطریق «کنسول Google Cloud» فعال‌سازی مجدد خودیاری را انجام دهید:

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

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

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

• شناسه کارخواه
• مورد استفاده خاص
• تاریخ انتقال هدف
• ارزیابی تأثیر کسب‌وکار

گزارش استفاده از شناسه کارخواه - از «گزارش‌های صورت‌حساب»

بررسی گزارش‌های «صورت‌حساب» به‌جای «سنجه‌های پروژه» می‌تواند برای کاربرانی که به سنجه‌های پروژه دسترسی ندارند مفید باشد—برای مثال، سرپرستان صورت‌حساب (به‌ویژه «شرکای پلاتفرم Maps»). درحالی‌که «گزارش‌های صورت‌حساب» ۱ تا ۲ روز تأخیر دارند، این مزیت را دارند که بیش‌از ۳۰ روز اطلاعات آماری استفاده و هزینه را نشان می‌دهند.

با دنبال کردن این مراحل می‌توانید استفاده از «شناسه مشتری» را ازطریق «کنسول Google Cloud» پایش کنید:

1. به صفحه صورت‌حساب > گزارش‌ها در «کنسول Google Cloud» پیمایش کنید.
2. (اختیاری، فقط برای شرکا مربوط است) فیلتری را برای انتخاب حساب فرعی صورت‌حساب موردنظر اعمال کنید.
3. داده‌های گزارش را براساس کلید برچسب goog-maps-api-key-suffix گروه‌بندی کنید. این برچسب نویسه‌های انتهایی کلید API را نمایش می‌دهد.
4. ترافیک «شناسه کارخواه» را با جستجوی ورودی‌هایی که در آن‌ها برچسب goog-maps-api-key-suffix وجود ندارد یا خالی است شناسایی کنید، زیرا این برچسب برای درخواست‌های «شناسه کارخواه» تکمیل نمی‌شود.
5. «واحد نگهداری کالا»هایی را که قرار نیست با درخواست‌های «میانای برنامه‌سازی کاربردی» منسوب شوند نادیده بگیرید—برای نمونه، واحدهای نگهداری کالای اشتراک.

عیب‌یابی

چگونه می‌توانیم ببینیم که درخواست ما ناموفق است یا نه؟

می‌توانید آمار خطای خود را در گراف‌های کد پاسخ بررسی کنید

خطای ApiNotActivatedMapError یا REQUEST_DENIED

اگر سرویس را در «پروژه ابری» خود فعال نکرده باشید، خطای ApiNotActivatedMapError یا REQUEST_DENIED را خواهید دید. برای فعال کردن سرویس، دستورالعمل‌ها را دنبال کنید.

‫RefererNotAllowedMapError خطا

اگر دامنه منبع شما به کلید API اضافه نشده باشد، خطای RefererNotAllowedMapError را خواهید دید. بخش «ایمن کردن کلید API» را بررسی کنید و دامنه خود را به کلید API اضافه کنید.

خطای OverQuotaMapError یا OVER_QUERY_LIMIT

اگر سهمیه پیکربندی‌شده شما برای پوشش ترافیک کافی نباشد، OverQuotaMapError یا OVER_QUERY_LIMIT را خواهید دید. بخش «تنظیمات سهمیه مرور» را بررسی کنید و سهمیه خود را براساس آن تنظیم کنید.

خطای «درخواست‌ها به این میانای برنامه‌سازی کاربردی باید ازطریق 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"
}