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

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

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

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

إدراج الخطأ

توضِّح القائمة التالية الأخطاء التي قد تواجهها عند استخدام واجهة برمجة التطبيقات 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، عليك إعادة محاولة تقديم الطلب بطريقة لا تؤدي إلى تعطُّل خوادم Goodle أو في حال تعذُّر تنفيذ الطلبات على نطاق واسع، لأنّ العديد من العملاء يحاولون إعادة محاولة تقديم الطلبات بتتابع سريع. يعني ذلك استخدام ميزة الرقود الأسي عند إعادة محاولة إرسال طلباتك. تجبرك ميزة "الوقت المتزايد للانتظار" على توزيع طلباتك على مدار الوقت، لمنح الخادم الوقت الكافي لاستعادة عافيته.

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

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

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

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

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

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

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

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

400: وسيطة غير صالحة

مفاتيح واجهة برمجة التطبيقات أو معلَمات طلب البحث أو أرقام تعريف المربّعات/مجموعات المربّعات أو الرمز المميّز للجلسة منتهية الصلاحية.

403: تم رفض الإذن

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

429: عدد كبير جدًا من الطلبات

تم استنفاد حصتك. يُرجى التواصل مع فريق دعم Google لزيادة حصتك.