دليل نقل معرّف العميل

نظرة عامة

لتعزيز أمان المصادقة وموثوقيتها، تم إيقاف معرّفات عملاء "منصة خرائط Google" نهائيًا اعتبارًا من 26 مايو 2025، ولن يعود بالإمكان استخدامها بعد 31 مايو 2026.

بدلاً من استخدام معرّف العميل، عليك استخدام بيانات اعتماد مفتاح واجهة برمجة التطبيقات للمصادقة على زيارات خدمة Google Maps API. يوضّح لك هذا الدليل كيفية الانتقال من استخدام أرقام تعريف العملاء إلى استخدام مفاتيح واجهة برمجة التطبيقات.

يرجى اتباع الخطوات التالية للبدء:

1. التحقّق من الاستخدام الحالي لمعرّف العميل
2. إعداد مفاتيح واجهة برمجة التطبيقات
3. مراجعة إعدادات الحصة
4. تعديل الرمز
5. مراقبة عدد الزيارات لمعرّف العميل
6. إيقاف معرّف العميل مؤقتًا

التحقّق من استخدام معرّف العميل الحالي

قبل بدء عملية نقل البيانات، أدرِج ما يلي:

• خدمات "منصة خرائط Google" التي تستخدمها مع معرّف العميل
• التطبيقات أو المواقع الإلكترونية أو الأنظمة التي تستخدم فيها معرّف العميل

أرسلت Google رسالة إلكترونية تتضمّن إشعارًا إلى العملاء المتأثّرين بشأن إيقاف معرّف العميل نهائيًا في مايو 2025. يمكنك أيضًا العثور على هذه المعلومات في رسالة الإشعار الإلكترونية.

في Cloud Console، يمكنك الاطّلاع على آخر حالة لاستخدام معرّف العميل في صفحة مقاييس "خرائط Google".

للاطّلاع على قائمة "خدمات منصة خرائط Google":

1. افتح صفحة المقاييس في Cloud Console.
2. فلترة استخدامك باستخدام الإعدادات التالية:
   • بيانات الاعتماد: اختَر "project_number:<numerical identifier>" فقط.
3. اضبط الفلتر التالي.
   • مجمّع حسب: واجهة برمجة التطبيقات

للحصول على تلميحات حول التطبيقات أو المواقع الإلكترونية أو الأنظمة:

لا تعرض Cloud Console تفاصيل تطبيقاتك أو مواقعك الإلكترونية أو أنظمتك. ولكن يمكنك العثور على بعض المؤشرات لمصادر الزيارات التي تستخدم معرّف العميل. اتّبِع الخطوات التالية:

1. افتح صفحة المقاييس في Cloud Console.
2. اختَر خدمة من "منصة خرائط Google" من القائمة المنسدلة.
3. فلترة استخدامك باستخدام الإعدادات التالية:
   • بيانات الاعتماد: اختَر "project_number:<numerical identifier>" فقط.
4. اضبط الفلتر التالي.
   • التجميع حسب: المنصة أو النطاق
5. كرِّر الخطوات بدءًا من الخطوة 2 لكل خدمة من &quot;منصة خرائط Google&quot; تريد التحقّق من عدد الزيارات إليها.

إعداد مفاتيح واجهة برمجة التطبيقات

ترتبط جميع أرقام تعريف العملاء بمشروع على Google Cloud، وسيمنحك استخدام مفتاح API من هذا المشروع إمكانية الوصول إلى الميزات نفسها التي سبق لك الوصول إليها باستخدام رقم تعريف العميل. ننصحك بنقل بياناتك إلى المشروع المرتبط لتجنُّب المشاكل المتعلّقة بالحِصص أو الميزات غير المتوفّرة.

1. ابحث عن مشروع السحابة الإلكترونية المرتبط بمعرّف العميل:
   • الأسئلة الشائعة حول نقل البيانات في البوابة
2. تأكَّد من أنّ مشروعك على Cloud مرتبط بحساب فوترة مفتوح.
3. أنشئ مفتاح واجهة برمجة تطبيقات جديدًا لترحيل معرّف العميل.
   • يمكنك إعادة استخدام أي مفاتيح حالية لواجهة برمجة التطبيقات في "مشروع Google Cloud".
   • يمكنك استخدام مفاتيح متعددة لواجهة برمجة التطبيقات من مشروع Cloud نفسه، مثلاً، لفصل عدد الزيارات لكل خدمة من خدمات &quot;منصة خرائط Google&quot;، أو لفصل عدد الزيارات من منصات مختلفة (المتصفّح وتطبيق الأجهزة الجوّالة وغير ذلك). يُرجى الرجوع إلى دليل الأمان للاطّلاع على أفضل الممارسات المتعلّقة بإدارة مفاتيح واجهة برمجة التطبيقات.

تأمين مفتاح واجهة برمجة التطبيقات

احرص على تأمين مفتاح واجهة برمجة التطبيقات لحمايته من الوصول غير المصرَّح به.

• اضبط قيودًا على التطبيق لمفتاح واجهة برمجة التطبيقات (مثل المواقع الإلكترونية أو عناوين IP أو تطبيقات Android أو تطبيقات iOS).
• اضبط قيود واجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات.

لمزيد من التفاصيل، يُرجى الاطّلاع على إرشادات الأمان في "منصة خرائط Google".

بالنسبة إلى Maps JavaScript API وMaps Static API وStreet View Static API، يمكنك نقل عناوين URL الموثوق بها المرتبطة بمعرّف العميل إلى القيود المفروضة على مفتاح واجهة برمجة التطبيقات. يمكنك العثور على قائمة بالمواقع الإحالية الموثوق بها في Cloud Console.

مراجعة إعدادات الحصة

تأكَّد من توفّر إعدادات الحصة المتوقّعة في مشروعك على Cloud. لا تحتاج إلى إجراء ذلك إلا إذا كنت تستدعي خدمات &quot;واجهة برمجة تطبيقات JavaScript لخرائط Google&quot; من جهة العميل باستخدام معرّف عميل. يمكنك الاطّلاع على إعدادات الحصة وتعديلها في صفحة حصص "خرائط Google".

مزيد من المعلومات عن تقارير الحصص

زيادة الحصة لخدمات Maps JavaScript API من جهة العميل

تحذير: إنّ استخدام معرّف العميل في الخدمات من جهة العميل لواجهة برمجة التطبيقات JavaScript الخاصة بخرائط Google لا يستهلك حصة المشروع. بعد الانتقال إلى مفتاح واجهة برمجة التطبيقات، سيستهلك استخدامك حصة المشروع. يجب التأكّد من توفّر مساحة كافية في الحصة قبل نقل البيانات.

إذا كنت تستخدم الخدمات التالية على Maps JavaScript API، ستلاحظ زيادة في استخدام الحصة بعد نقل مفتاح واجهة برمجة التطبيقات.

راجِع إعدادات الحصة الحالية والاستخدام الحالي، ثم عدِّل حدود الحصة وفقًا لذلك.

1. تحقَّق مما إذا كنت تستخدم خدمات Maps JavaScript API من جهة العميل مع معرّف عميل.
   • افتح صفحة المقاييس في Cloud Console.
   • فلترة استخدامك باستخدام الإعدادات التالية:
     • مجمّعة حسب: طريقة واجهة برمجة التطبيقات
     • بيانات الاعتماد: اختَر "project_number:<numerical identifier>" فقط.
   • بعد ذلك، ستظهر لك قائمة بأسماء الطرق مع عدد الزيارات في الرسم البياني "الزيارات حسب طريقة واجهة برمجة التطبيقات".

طريقة واجهة برمجة التطبيقات	الخدمة من جهة العميل	الخدمة التي سيتم تعديل الحصة فيها
google.routes.Directions.Javascript	خدمة "الاتجاهات"	Directions API
google.routes.DistanceMatrix.Javascript	خدمة Distance Matrix	Distance Matrix API
google.maps.Elevation.Javascript	Elevation Service	Elevation API
google.places.Geocoding.Javascript	خدمة ترميز المواقع الجغرافية	Geocoding API
‫google.places.*.Javascript، باستثناء google.places.Geocoding.Javascript	Places Library	واجهة برمجة تطبيقات الأماكن

• إذا كنت لا تستخدم طرق واجهة برمجة التطبيقات هذه، لن تحتاج إلى القلق بشأن إعدادات الحصة، لأنّ عدد الزيارات التي يتمّ تسجيلها باستخدام رقم تعريف العميل يستهلك حصّة مشروعك.
• تقدير نسبة استهلاكك من حصة معرّف العميل
  • بالنسبة إلى كل خدمة، ضَع علامة في المربّعين "لكل ثانية" و"لكل يوم" ضمن مستوى التفاصيل.
  • مخطط "عدد الطلبات في الثانية": اضرب الحد الأقصى لعدد الزيارات في 60 للحصول على الحصة الإضافية المطلوبة في الدقيقة.
  • الرسم البياني اليومي: يجب أن تكون ذروة عدد الزيارات هي الحصة الإضافية المطلوبة يوميًا.
• تعديل حصتك على خدمات "منصة خرائط Google" المعنية
  • استنادًا إلى اسم الطريقة الذي تجده في الخطوة 1، اضبط الحصة على الخدمات المعنية.

تعديل الرمز

استبدال مَعلمة العميل بمَعلمة المفتاح

عدِّل بيانات المصادقة من URL&client={value} إلى URL&key={value} في طلبات البيانات من واجهة برمجة التطبيقات الصادرة من "منصة Google للتسويق". إذا كانت تطبيقاتك تستخدم بروتوكول HTTP للوصول إلى خدمات "منصّة Google للتسويق"، عليك تعديلها لاستخدام بروتوكول HTTPS.

تعديل مَعلمة القناة لإعداد التقارير

يمكنك تتبُّع استخدامك لكل قناة من خلال تحديد مَعلمة القناة في طلبات البيانات من واجهة برمجة التطبيقات. لا تتيح مفاتيح واجهة برمجة التطبيقات سوى القيم الرقمية لمعلَمة القناة. إذا كنت تستخدم معرّف العميل مع أي قيم غير رقمية لمَعلمة القناة، عليك تعديلها إلى قيمة رقمية من القيم المتوافقة.

يمكنك الاطّلاع على إعداد التقارير في "منصة خرائط Google" لمزيد من المعلومات.

إزالة مَعلمة التوقيع للخدمات على الويب

بالنسبة إلى واجهات برمجة التطبيقات لخدمة الويب التالية، لا تكون مَعلمة التوقيع مطلوبة عند الوصول إليها باستخدام مفتاح واجهة برمجة التطبيقات. ما عليك سوى إزالة مَعلمة التوقيع من طلبات واجهة برمجة التطبيقات.

• Directions API (الإصدار القديم)
• Distance Matrix API (الإصدار القديم)
• Geocoding API
• Elevation API
• Time Zone API

يمكنك الاطّلاع على نظرة عامة على خطة Premium للحصول على مزيد من المعلومات.

Signing Secret لواجهات برمجة التطبيقات الخاصة بالصور

لا يزال كل من Maps Static API وStreet View Static API يتطلبان مَعلمة التوقيع. ويقبلون عددًا قليلاً من الطلبات بدون توقيع لأغراض الاختبار، ولكنهم يبدأون في رفض الطلبات عند بلوغ الحدّ الأقصى في الإصدار العلني. استبدِل سر التوقيع الخاص بمعرّف العميل بسر التوقيع الخاص بمفتاح واجهة برمجة التطبيقات. يمكنك استخدام خوارزمية التوقيع نفسها، ولكن يجب استخدام سر توقيع آخر. لمزيد من المعلومات، يمكنك الاطّلاع على استخدام توقيع رقمي.

تحذير: قبل نشر تغييرات الرموز البرمجية في مرحلة الإنتاج، تأكَّد من عدم تأثُّر الوظائف الشاملة.

مراقبة عدد الزيارات الواردة من معرّف العميل

بعد عملية النشر، تأكَّد من نقل الزيارات بنجاح باستخدام لوحات بيانات Cloud Console. ستلاحظ انخفاضًا في عدد الزيارات التي تستخدم معرّف العميل، والذي يظهر بالتنسيق "project_number:123456" في لوحة البيانات عند التجميع حسب بيانات الاعتماد.

إيقاف معرّف العميل مؤقتًا

ننصح المطوّرين بشدة بإيقاف معرّفات العملاء مؤقتًا بعد نقل البيانات. والغرض من ذلك هو حماية بيانات الاعتماد من أي زيارات غير مقصودة، والتأكّد من أنّ أي استخدام متبقٍّ لمعرّف العميل ليس مهمًا (مثل الاختبارات وذاكرات التخزين المؤقت وبرامج التتبّع وما إلى ذلك) ويمكن أن يعرض أخطاءً بدون أن يؤثّر ذلك في النشاط التجاري. يمكنك إيقاف معرّف العميل مؤقتًا في Cloud Console. لمزيد من التفاصيل، يُرجى الاطّلاع على نظرة عامة على مصادقة خطة Premium.

تحديد المشاكل وحلّها

كيف يمكننا معرفة ما إذا كان طلبنا يتعذّر تنفيذه أم لا؟

يمكنك الاطّلاع على إحصاءات الأخطاء في الرسومات البيانية لرموز الاستجابة.

خطأ ApiNotActivatedMapError أو REQUEST_DENIED

سيظهر لك الخطأ ApiNotActivatedMapError أو REQUEST_DENIED إذا لم تفعّل الخدمة في مشروعك على السحابة الإلكترونية. اتّبِع التعليمات لتفعيل الخدمة.

خطأ واحد (RefererNotAllowedMapError)

سيظهر لك الخطأ RefererNotAllowedMapError إذا لم تتم إضافة نطاق المصدر إلى مفتاح واجهة برمجة التطبيقات. راجِع قسم "تأمين مفتاح واجهة برمجة التطبيقات"، وأضِف نطاقك إلى مفتاح واجهة برمجة التطبيقات.

خطأ OverQuotaMapError أو OVER_QUERY_LIMIT

سيظهر لك الرمز OverQuotaMapError أو OVER_QUERY_LIMIT إذا لم يكن الحصص المحدّدة كافية لتغطية عدد الزيارات. راجِع قسم "مراجعة إعدادات الحصة" وعدِّل حصتك وفقًا لذلك.

رسالة الخطأ "يجب أن تتم الطلبات إلى واجهة برمجة التطبيقات هذه عبر طبقة المقابس الآمنة"

إذا تلقّيت رسالة الخطأ التالية، عليك تعديل طلبات البيانات من واجهة برمجة التطبيقات من "http://" إلى "https://".

{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}