هذا المنتج أو الميزة في مرحلة إطلاق "المعاينة" في مرحلة ما قبل التوفّر للجمهور العام (ما قبل التوفّر للجمهور العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات هنا متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع عروض مرحلة ما قبل التوفّر للجمهور العام لبنود الخدمة المحدّدة في "منصة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

أفضل الممارسات لاستخدام خدمات الويب في Map Management API

خدمات الويب في "منصة خرائط Google" هي مجموعة من واجهات HTTP لخدمات Google التي توفّر بيانات جغرافية لتطبيقات الخرائط.

يوضّح هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد طلبات خدمة الويب ومعالجة ردود الخدمة. يُرجى الرجوع إلى دليل المطوّرين للحصول على المستندات الكاملة الخاصة بواجهة Map Management API.

ما هي خدمة الويب؟

خدمات الويب في "منصة خرائط Google" هي واجهة لطلب بيانات Maps API من خدمات خارجية واستخدام البيانات في تطبيقات "خرائط Google". تم تصميم هذه الخدمات لاستخدامها مع خريطة، وذلك وفقًا لقيود الترخيص الواردة في بنود خدمة "منصة خرائط Google".

تستخدم خدمات الويب في واجهات Maps API طلبات HTTP(S) إلى عناوين URL معيّنة، مع تمرير مَعلمات عناوين URL و/أو بيانات POST بتنسيق JSON كمعلمات للخدمات. وبشكل عام، تعرض هذه الخدمات البيانات في نص الرد بتنسيق JSON ليتم تحليلها و/أو معالجتها من خلال تطبيقك.

يوضّح المثال التالي طلب REST GET إلى طريقة list Map Configs:

https://mapmanagement.googleapis.com/v2beta/projects/PROJECT_NUMBER_OR_ID/mapConfigs

أدرِج طلب رمز OAuth المميز في Authorization header من الطلب.

الوصول إلى SSL/TLS

يجب استخدام HTTPS لجميع طلبات "منصة خرائط Google" التي تستخدم مفاتيح واجهة برمجة التطبيقات أو تحتوي على بيانات المستخدمين. قد يتم رفض الطلبات التي يتم إجراؤها عبر HTTP والتي تحتوي على بيانات حساسة.

إنشاء عنوان URL صالح

قد يبدو لك أنّ عنوان URL "صالح" هو أمر بديهي، ولكن هذا ليس صحيحًا تمامًا. قد يحتوي عنوان URL تم إدخاله في شريط العناوين في متصفح، على سبيل المثال، على أحرف خاصة (مثل "上海+中國")، ويحتاج المتصفح إلى ترجمة هذه الأحرف داخليًا إلى ترميز مختلف قبل الإرسال. وبالمثل، قد يتعامل أي رمز برمجي ينشئ أو يقبل إدخال UTF-8 مع عناوين URL التي تتضمّن أحرف UTF-8 على أنّها "صالحة"، ولكنّه سيحتاج أيضًا إلى ترجمة هذه الأحرف قبل إرسالها إلى خادم ويب. تُعرف هذه العملية باسم ترميز عنوان URL أو الترميز بالنسبة المئوية.

الرموز الخاصة

نحتاج إلى ترجمة الأحرف الخاصة لأنّه يجب أن تتوافق جميع عناوين URL مع بنية معرّف الموارد الموحّد (URI). يعني ذلك أنّ عناوين URL يجب أن تتضمّن مجموعة فرعية خاصة من أحرف ASCII فقط، وهي الرموز الأبجدية الرقمية المألوفة وبعض الأحرف المحجوزة لاستخدامها كأحرف تحكّم ضمن عناوين URL. يوضّح الجدول التالي هذه الأحرف:

ملخّص الأحرف الصالحة في عناوين URL

ضبط	الأحرف	استخدام عنوان URL
أحرف أبجدية رقمية	أ ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف ق ك ل م ن هـ و ي أ إ آ ؤ ئ ء ة ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف ق ك ل م ن هـ و ي أ إ آ ؤ ئ ء ة ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف ق ك ل م ن هـ و ي أ إ آ ؤ ئ ء ة ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف ق ك ل م ن هـ و ي أ إ آ ؤ ئ ء ة ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف	سلاسل النصوص واستخدام المخطط (`http`) والمنفذ (`8080`) وما إلى ذلك
غير محجوز	- _ . ~	السلاسل النصية
تم الحجز	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	أحرف التحكّم و/أو السلاسل النصية

عند إنشاء عنوان URL صالح، يجب التأكّد من أنّه يحتوي على الأحرف الموضّحة في الجدول فقط. يؤدي الالتزام بمجموعة الأحرف هذه في عناوين URL بشكل عام إلى مشكلتَين، إحداهما تتعلق بالحذف والأخرى بالاستبدال:

تتوفّر أحرف تريد التعامل معها خارج المجموعة المذكورة أعلاه. على سبيل المثال، يجب ترميز الأحرف في اللغات الأجنبية، مثل 上海+中國، باستخدام الأحرف المذكورة أعلاه. وفقًا للاتفاقيات الشائعة، غالبًا ما يتم تمثيل المسافات (غير المسموح بها ضمن عناوين URL) باستخدام علامة الجمع '+' أيضًا.
تتضمّن المجموعة أعلاه أحرفًا محجوزة، ولكن يجب استخدامها حرفيًا. على سبيل المثال، يتم استخدام ? ضمن عناوين URL للإشارة إلى بداية سلسلة طلب البحث. إذا أردت استخدام السلسلة "‎? and the Mysterions"، عليك ترميز الحرف '?'.

يتم ترميز جميع الأحرف التي سيتم ترميزها باستخدام عنوان URL باستخدام الحرف '%' وقيمة سداسية عشرية مكوّنة من حرفين تتوافق مع حرف UTF-8. على سبيل المثال، سيتم ترميز 上海+中國 في UTF-8 على شكل %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B في عنوان URL. سيتم ترميز السلسلة ? and the Mysterians باستخدام عنوان URL على النحو التالي: %3F+and+the+Mysterians أو %3F%20and%20the%20Mysterians.

الأحرف الشائعة التي يجب ترميزها

في ما يلي بعض الأحرف الشائعة التي يجب ترميزها:

حرف غير آمن	القيمة المشفرة
مسافة	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

قد يكون تحويل عنوان URL الذي تتلقّاه من بيانات أدخلها المستخدم أمرًا صعبًا في بعض الأحيان. على سبيل المثال، قد يُدخل المستخدم عنوانًا على النحو التالي: "شارع 5 وشارع مين". بشكل عام، يجب إنشاء عنوان URL من أجزائه، مع التعامل مع أي بيانات أدخلها المستخدم كأحرف حرفية.

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

الاستخدام المهذّب لواجهات Google API

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

الرقود الأسي الثنائي

في حالات نادرة، قد يحدث خطأ أثناء تنفيذ طلبك، وقد تتلقّى رمز استجابة HTTP 4XX أو 5XX، أو قد يتعذّر ببساطة إنشاء اتصال TCP في مكان ما بين جهازك وخادم Google. في كثير من الأحيان، يجدر إعادة محاولة الطلب لأنّ الطلب اللاحق قد ينجح عندما يفشل الطلب الأصلي. ومع ذلك، من المهم عدم تكرار طلباتك إلى خوادم Google بشكل متواصل. يمكن أن يؤدي هذا السلوك المتكرّر إلى زيادة الحمل على الشبكة بين جهازك وGoogle، ما يتسبب في حدوث مشاكل للعديد من الأطراف.

والحلّ الأفضل هو إعادة المحاولة مع زيادة حالات التأخير بين المحاولات. عادةً ما يتم زيادة التأخير بعامل ضربي مع كل محاولة، وهو أسلوب يُعرف باسم الرقود الأسي الثنائي.

على سبيل المثال، لنفترض أنّ هناك تطبيقًا يريد إرسال الطلب التالي إلى Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

يوضّح مثال Python التالي كيفية تقديم الطلب مع التراجع الأسي:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

عليك أيضًا الحرص على عدم وجود رمز إعادة محاولة أعلى في سلسلة طلبات التطبيق يؤدي إلى تكرار الطلبات بشكل متسلسل وسريع.

الطلبات المتزامنة

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

على سبيل المثال، لنفترض تطبيقًا يعرض الوقت في المنطقة الزمنية الحالية. من المحتمل أنّ يضبط هذا التطبيق منبّهًا في نظام تشغيل الجهاز العميل لتنبيهه في بداية الدقيقة كي يتمكّن من تعديل الوقت المعروض. يجب ألّا يرسل التطبيق أي طلبات بيانات من واجهة برمجة التطبيقات كجزء من عملية المعالجة المرتبطة بهذا التنبيه.

إنّ إجراء طلبات إلى واجهة برمجة التطبيقات استجابةً لمنبّه ثابت أمر غير جيد لأنّه يؤدي إلى مزامنة الطلبات مع بداية الدقيقة، حتى بين الأجهزة المختلفة، بدلاً من توزيعها بالتساوي على مدار الوقت. سيؤدي تطبيق مصمّم بشكل سيئ إلى حدوث ارتفاع كبير في عدد الزيارات بمقدار ستين ضعفًا عن المستويات العادية في بداية كل دقيقة.

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

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

معالجة الردود

يناقش هذا القسم كيفية استخراج هذه القيم بشكل ديناميكي من ردود خدمة الويب.

تقدّم خدمات الويب في "خرائط Google" ردودًا يسهل فهمها، ولكنّها ليست سهلة الاستخدام تمامًا. عند تنفيذ استعلام، من المحتمل أنّك تريد استخراج بعض القيم المحدّدة بدلاً من عرض مجموعة من البيانات. بشكل عام، عليك تحليل الردود الواردة من خدمة الويب واستخراج القيم التي تهمّك فقط.

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

أفضل الممارسات لاستخدام خدمات الويب في Map Management API تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.