معالجة الأخطاء

بعد تقديم طلب، قد تتلقّى ردًا يحتوي على تفاصيل الخطأ.

المربّعات ثنائية الأبعاد وصور "التجوّل الافتراضي"

توضِّح القائمة التالية الأخطاء التي قد تواجهها عند استخدام التنسيق 2D للشرائح وصور "التجوّل الافتراضي".

إدراج الخطأ

توضِّح القائمة التالية الأخطاء التي قد تواجهها عند استخدام واجهة برمجة التطبيقات Map Tiles API.

required
لا يتضمّن طلبك مَعلمة عنوان URL. يُرجى العِلم أنّ رسالة الخطأ تشير إلى المَعلمة غير المتوفّرة.
"notFound" و"invalid"

قيم x أو y أو z خارج النطاق.

  • بالنسبة إلى مربّعات الخريطة العادية، يعتمد الحد الأقصى لمستوى التكبير على مربّع الخريطة المعنيّ وعلى خيارات الخريطة التي طلبتها.

  • بالنسبة إلى مربّعات الخريطة العادية، يجب أن تكون إحداثية x ضمن النطاق [0, (2^zoom)-1].

  • بالنسبة إلى مربّعات الخريطة العادية، يجب أن يكون الإحداثي y ضمن النطاق [0, (2^(zoom-1))-1].

  • بالنسبة إلى مربّعات "التجوّل الافتراضي"، يجب أن يتراوح التكبير بين صفر وخمسة.

  • بالنسبة إلى مربّعات "التجوّل الافتراضي"، تكون نطاقات إحداثيات x وy مماثلة لمربّعات الخريطة العادية، إلى أن تصل إلى مستوى التكبير/التصغير الخامس. في هذه المرحلة، تكون قيم القصوى هي imageHeight أو imagewidth مقسومة على tileHeight أو tileWidth.

forbidden: لا يتضمّن الطلب مفتاح واجهة برمجة تطبيقات صالحًا.

expired
انتهت صلاحية الرمز المميَّز session. يكون الرمز المميّز للجلسة صالحًا لمدة أسبوعَين من وقت إنشائه. يُرجى العِلم أنّ هذه الشروط قد تتغيّر بدون إشعار. إذا ظهر لك هذا الخطأ، عليك الحصول على رمز مميّز جديد للجلسة، كما هو موضّح في مقالة استخدام الرموز المميّزة للجلسات.
badRequest

طلبك غير صالح. تشمل الأسباب الشائعة لذلك ما يلي:

  • حدّدت نوع خريطة terrain بدون تضمين طبقة roadmap.

  • لقد أدرجت صفيف styles لنوع خريطة غير خريطة خارطة الطريق.

  • لقد أرسلت قيمة خط الطول/العرض، بالإضافة إلى رقم تعريف بانورامي في طلب بشأن البيانات الوصفية لميزة "التجوّل الافتراضي".

"quotaExceeded" و"rateLimitExceeded"

تجاوز تطبيقك الحصة المسموح بها له أو تجاوز العدد المسموح به من طلبات البحث في الثانية.

مثال على الخطأ

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "errors": [
      {
        "message": "The request is missing a valid API key.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}

إعادة محاولة إرسال الطلبات

عندما يتعذّر إكمال الطلبات بسبب الخطأَين quotaExceeded وrateLimitExceeded، عليك إعادة محاولة إكمال طلبك بطريقة لا تؤدي إلى إغراق خوادم Google بطلبات معطّلة أو أخطاء على نطاق واسع، لأنّ العديد من العملاء يحاولون إعادة محاولة إكمال الطلبات بشكلٍ متتابع وبسرعة. وهذا يعني استخدام خوارزمية الرقود الأسي الثنائي عند إعادة محاولة إرسال طلباتك. تجبرك ميزة "الوقت المتزايد للانتظار" على توزيع طلباتك على مدار الوقت، لمنح الخادم الوقت الكافي لاستعادة عافيته.

على سبيل المثال، إذا تعذّر إكمال طلب، يمكنك إعادة المحاولة بعد ثانية واحدة. إذا تعذّرت هذه المحاولة أيضًا، يُرجى إعادة المحاولة بعد ثانيتين. إذا تعذّر تنفيذ هذا الطلب أيضًا، أعِد المحاولة بعد أربع ثوانٍ. وبالتالي، يمكنك توزيع كل طلب على التوالي بفعالية من خلال مضاعفة المدة الزمنية بين الطلبات.

المربّعات الثلاثية الأبعاد

قد لا تكون الأخطاء الواردة من خادم Google واضحة لك لأنّك تحصل على اللوحات المعروضة بدقة عالية من خلال أداة عرض مسؤولة عن التعامل مع أخطاء الخادم.

أخطاء أداة عرض البلاط

على سبيل المثال، يتعذّر عادةً على أداة التقديم CesiumJS إكمال عملية التقديم بدون إشعار عند حدوث أخطاء في الخادم، ما قد يؤدي إلى حدوث أيٍّ من الأعطال أو الشاشات الفارغة أو عدم تحميل وحدات أساسية معيّنة.

تعتمد الطريقة التي تستخدمها لتصحيح أخطاء الخادم على معالج العرض المُستخدَم. بالنسبة إلى برامج التقديم المستندة إلى المتصفّح، مثل CesiumJS، يمكنك فحص عدد زيارات الشبكة باستخدام أدوات مضمّنة في معظم المتصفّحات. على سبيل المثال، يمكنك استخدام أدوات مطوّري البرامج في Chrome.

الأخطاء الشائعة

تحتوي القائمة التالية على تفاصيل عن الأخطاء الأكثر شيوعًا التي قد تواجهها.

400: وسيطة غير صالحة
مفاتيح واجهة برمجة التطبيقات أو مَعلمات طلب البحث أو معرّفات الوحدات المربّعة/مجموعة الوحدات المربّعة أو رمز جلسة منتهي الصلاحية
403: تم رفض الإذن
مفتاح واجهة برمجة التطبيقات غير متوفّر أو لا يتوفّر اتصال طبقة المقابس الآمنة أو لم تتم إضافة مفتاح واجهة برمجة التطبيقات إلى القائمة المسموح بها للشرائح الثلاثية الأبعاد تواصَل مع فريق دعم Google مع إرسال رقم تعريف مشروعك ليتمّت إضافتك إلى القائمة المسموح بها لوظائف "الشرائح الثلاثية الأبعاد" في Map Tiles API.
429: عدد كبير جدًا من الطلبات
تم استنفاد حصتك. يُرجى التواصل مع فريق الدعم في Google لزيادة حصتك.