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

نظرة عامة

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

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

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

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

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

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

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

أرسلت Google رسالة إلكترونية تتضمّن إشعارًا إلى العملاء المتأثّرين بشأن إيقاف المعرّف <0x0A>client نهائيًا في مايو 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. ابحث عن مشروع Cloud المرتبط به معرّف العميل الخاص بك:
   • الأسئلة الشائعة حول نقل البيانات إلى البوابة
2. تأكَّد من أنّ مشروعك على Cloud مرتبط بحساب فوترة مفتوح.
3. أنشئ مفتاح واجهة برمجة تطبيقات جديدًا لترحيل معرّف العميل.
   • يمكنك إعادة استخدام أي مفاتيح حالية لواجهة برمجة التطبيقات في "مشروع السحابة الإلكترونية".
   • يمكنك استخدام مفاتيح متعددة لواجهة برمجة التطبيقات من مشروع 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; من جهة العميل باستخدام معرّف عميل. يمكنك الاطّلاع على إعدادات الحصة وتعديلها في صفحة حصص &quot;خرائط Google&quot;.

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

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

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

إذا كنت تستخدم الخدمات التالية على 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	مكتبة الأماكن	واجهة برمجة تطبيقات الأماكن

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

تعديل الرمز

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

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

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

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

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

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

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

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

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

Signing Secret for Imagery APIs

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

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

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

بعد عملية النشر، تأكَّد من نقل الزيارات بنجاح باستخدام لوحات بيانات 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"
}