راهنمای مهاجرت شناسه مشتری، راهنمای مهاجرت شناسه مشتری

نمای کلی

به منظور افزایش امنیت و قابلیت اطمینان احراز هویت، شناسه‌های سرویس گیرنده پلتفرم Maps از ۲۶ مه ۲۰۲۵ منسوخ شده‌اند و پس از ۳۱ مه ۲۰۲۶ دیگر قابل استفاده نیستند.

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

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

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

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

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

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

Google در ماه مه 2025 یک ایمیل اعلان برای مشتریان متاثر درباره منسوخ شدن شناسه مشتری ارسال کرد. می‌توانید این اطلاعات را در ایمیل اعلان نیز بیابید.

در Cloud Console، می‌توانید آخرین وضعیت استفاده از Client ID خود را در صفحه متریک Google Maps بررسی کنید.

برای لیستی از خدمات پلتفرم Maps :

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

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

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

1. صفحه Metrics را در Cloud Console باز کنید.
2. یک سرویس Maps Platform را از منوی کشویی انتخاب کنید.
3. استفاده خود را با تنظیمات زیر فیلتر کنید:
   • اعتبار: فقط "project_number:<numerical identifier>" را انتخاب کنید.
4. فیلتر زیر را تنظیم کنید.
   • گروه بندی بر اساس: پلتفرم یا دامنه
5. از مرحله 2 برای هر سرویس Maps Platform که باید ترافیک را بررسی کنید، این کار را تکرار کنید.

کلیدهای API را آماده کنید

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

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

کلید API خود را ایمن کنید

مطمئن شوید که کلید API خود را ایمن کنید تا کلید خود را از دسترسی غیرمجاز محافظت کنید.

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

برای جزئیات بیشتر به راهنمای امنیتی پلتفرم Google Maps مراجعه کنید.

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

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

مطمئن شوید که انتظار تنظیمات سهمیه را در پروژه ابری خود داشته اید. فقط در صورتی باید این کار را انجام دهید که خدمات سمت سرویس گیرنده Maps JavaScript API را از شناسه مشتری فراخوانی کنید. می توانید تنظیمات سهمیه خود را در صفحه سهمیه Google Maps بررسی و تنظیم کنید.

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

افزایش سهمیه برای خدمات Maps JavaScript API سمت سرویس گیرنده

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

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

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

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

روش API	خدمات سمت مشتری	سرویس تعدیل سهمیه
google.routes.Directions.Javascript	خدمات مسیرها	Directions API
google.routes.DistanceMatrix.Javascript	سرویس ماتریس فاصله	Distance Matrix API
google.maps.Elevation.Javascript	سرویس ارتفاع	Elevation API
google.places.Geocoding.Javascript	سرویس ژئوکدینگ	API کدگذاری جغرافیایی
google.places.*.Javascript، غیر از google.places.Geocoding.Javascript	کتابخانه مکان ها	Places API

• اگر از آن روش‌های API استفاده نمی‌کنید، لازم نیست نگران تنظیمات سهمیه باشید، زیرا ترافیک شناسه مشتری شما از قبل سهمیه پروژه شما را مصرف می‌کند.
• میزان استفاده از سهمیه شناسه مشتری خود را تخمین بزنید
  • برای هر یک از سرویس‌ها، هم مقدار Per Second و هم در Per Day را بررسی کنید.
  • نمودار در هر ثانیه: برای نیازهای اضافی به سهمیه در دقیقه، اوج ترافیک را در 60 ضرب کنید.
  • نمودار در روز: اوج ترافیک باید سهمیه اضافی در روز باشد.
• سهمیه خود را در خدمات مربوطه Maps Platform تنظیم کنید
  • بر اساس نام روشی که در مرحله 1 یافتید، سهمیه خدمات مربوطه را تنظیم کنید.

کد خود را به روز کنید

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

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

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

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

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

حذف پارامتر امضا برای خدمات وب

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

• Directions API (Legacy)
• Distance Matrix API (قدیمی)
• API کدگذاری جغرافیایی
• Elevation API
• API منطقه زمانی

برای اطلاعات بیشتر به نمای کلی طرح Premium مراجعه کنید.

Signing Secret for Imagery API

Maps Static API و Street View Static API همچنان به پارامتر امضا نیاز دارند. آنها تعداد کمی از درخواست‌ها را بدون امضا برای اهداف آزمایشی می‌پذیرند، اما پس از رسیدن به آستانه تولید شما شروع به شکست می‌کنند. راز امضای خود را از رمز شناسه مشتری به رمز امضای کلید API جایگزین کنید. می توانید از همان الگوریتم امضا استفاده کنید، اما باید از یک رمز امضای دیگر استفاده کنید. برای کسب اطلاعات بیشتر، به استفاده از امضای دیجیتال مراجعه کنید.

هشدار: قبل از استقرار تغییرات کد در تولید، بررسی کنید که عملکرد پایان به انتها تحت تأثیر قرار نگرفته است.

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

پس از استقرار، تأیید کنید که ترافیک شما با استفاده از داشبوردهای Cloud Console با موفقیت منتقل شده است. کاهش در ترافیک شناسه مشتری خود را مشاهده خواهید کرد، که در قالب "project_number:123456" در داشبورد هنگام گروه بندی بر اساس اطلاعات کاربری نشان داده می شود.

شناسه مشتری خود را مکث کنید

ما قویاً توصیه می کنیم که توسعه دهندگان شناسه های مشتری را پس از انتقال موقتاً متوقف کنند. این برای محافظت از اعتبار شما در برابر هرگونه ترافیک ناخواسته و تأیید این است که هرگونه استفاده باقی مانده از شناسه مشتری شما حیاتی نیست (مثلاً آزمایش، حافظه پنهان، ربات ها، ...) و می تواند خطاها را بدون ایجاد تأثیر تجاری برگرداند. می‌توانید شناسه مشتری خود را در Cloud Console متوقف کنید. برای جزئیات بیشتر به بررسی اجمالی تأیید اعتبار طرح Premium مراجعه کنید.

عیب یابی

چگونه می توانیم ببینیم که آیا درخواست ما شکست خورده است یا خیر؟

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

ApiNotActivatedMapError یا خطای REQUEST_DENIED

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

خطای RefererNotAllowedMapError

اگر دامنه منبع شما به کلید API اضافه نشده باشد، خطای RefererNotAllowedMapError را مشاهده خواهید کرد. بخش "Secure your API key" را علامت بزنید و دامنه خود را به کلید API اضافه کنید.

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"
}