ندعوك للانضمام إلينا في يوم منتدى مطوّري "منصة خرائط Google" القادم في سان فرانسيسكو في ديسمبر. قدِّم طلبك الآن لحضور الفعالية.

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

أفضل الممارسات لاستخدام Street View Static API

تُنشئ واجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط Google"، وهي مجموعة من واجهات HTTP، صورًا لتضمينها مباشرةً في صفحة الويب.

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

يصف هذا الدليل بعض الممارسات الشائعة المفيدة لإعداد طلبات خدمة الصور والويب ومعالجة ردود الخدمة. لمزيد من المعلومات حول Street View Static API، يُرجى الاطّلاع على دليل المطوّر.

تعمل واجهة برمجة تطبيقات التجوّل الافتراضي الثابتة كواجهة برمجة تطبيقات ويب ثابتة، بينما تعمل خدمة البيانات الوصفية كخدمة ويب. لمزيد من المعلومات حول خدمة البيانات الوصفية، يُرجى الاطّلاع على البيانات الوصفية لصور "التجوّل الافتراضي".

ما هي واجهة برمجة التطبيقات الثابتة للويب؟

تتيح لك واجهات برمجة التطبيقات الثابتة على الويب في "منصة خرائط Google" تضمين صورة من "خرائط Google" في صفحة الويب بدون الحاجة إلى استخدام JavaScript أو تحميل أي صفحة ديناميكية. تنشئ واجهات برمجة التطبيقات الثابتة للويب صورة استنادًا إلى مَعلمات عناوين URL التي يتم إرسالها باستخدام طلب HTTPS عادي.

يأخذ طلب بيانات من واجهة برمجة التطبيقات للتجوّل الافتراضي الثابت الشكل التالي:

  https://www.googleapis.com/streetview/z/x/y?parameters

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

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

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

يكون طلب البيانات الوصفية في Street View Static API على النحو التالي:

https://maps.googleapis.com/maps/api/streetview/parameters

الوصول إلى بروتوكول طبقة المقابس الآمنة (SSL) وبروتوكول أمان طبقة النقل (TLS)

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

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

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

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

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

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

ضبط	الأحرف	استخدام عناوين URL
أحرف أبجدية رقمية	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	السلاسل النصية واستخدام المخطط (`http`) والمنفذ (`8080`) وما إلى ذلك
غير محجوز	- _ . ~	سلاسل نصية
تم الحجز	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	أحرف التحكّم و/أو السلاسل النصية

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

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

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

الرموز الشائعة التي تحتاج إلى ترميز

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

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

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

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

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

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

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

في حالات نادرة، قد يحدث خطأ في طلبك، وقد تتلقّى رمز استجابة 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


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

يُرجى التأكّد من عدم وجود رمز إعادة محاولة في سلسلة طلبات التطبيق يؤدي إلى تكرار الطلبات بشكل متتالٍ وسريع.

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

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

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

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

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

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

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

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

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

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

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