إجراء طلبات البيانات من واجهة برمجة التطبيقات الأولى

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

إجراء مكالمات HTTP

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

ونقدّم أيضًا بعض مكتبات العملاء إذا كنت لا تريد إجراء استدعاءات HTTP مباشرة.

المتطلبات الأساسية

  1. يجب أن يكون لديك حساب على Google للوصول إلى وحدة تحكّم Google API وطلب مفتاح واجهة برمجة تطبيقات وتسجيل تطبيقك.

  2. يمكنك إنشاء مشروع في Google Developers Console والحصول على بيانات اعتماد تفويض حتى يتمكن تطبيقك من إرسال طلبات بيانات من واجهة برمجة التطبيقات.

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

    1. انتقِل إلى وحدة تحكم واجهة برمجة التطبيقات واختَر المشروع الذي سجّلته للتو.
    2. انتقِل إلى صفحة واجهات برمجة التطبيقات المفعّلة. تأكّد من أن واجهة برمجة التطبيقات لميزة "التجوّل الافتراضي من Google" مُدرجة في قائمة واجهات برمجة التطبيقات المفعّلة. وإذا لم يكن الأمر كذلك، عليك فتح مكتبة واجهة برمجة التطبيقات وتفعيل واجهة برمجة التطبيقات.

  4. اقرأ دليل المصادقة للتعرّف على كيفية تنفيذ تفويض OAuth 2.0.

  5. التعرّف على المفاهيم الأساسية لتنسيق بيانات JavaScript Object Notation (JSON) JSON هو تنسيق بيانات شائع مستقل عن اللغة، يقدّم تمثيلاً نصيًا بسيطًا لبنية البيانات العشوائية. لمزيد من المعلومات، راجع json.org‎‏.

الحصول على مفتاح واجهة برمجة تطبيقات

لأغراض المصادقة والحصة، ستحتاج إلى استخدام واجهة برمجة التطبيقات Google Street View Publish API مع بيانات الاعتماد التي تم إنشاؤها في Developers Console.

  1. انتقِل إلى صفحة بيانات الاعتماد في Developers Console.
  2. إذا كان لديك مفتاح واجهة برمجة تطبيقات، يمكنك استخدام القيمة منه. بخلاف ذلك، يمكنك إنشاء مفتاح جديد من خلال اختيار مفتاح واجهة برمجة التطبيقات من قائمة بيانات الاعتماد الجديدة.

الحصول على رمز الدخول

  1. انتقِل إلى منصة Google Developers OAuth 2.0 Playground.
  2. انقر على قائمة الإعدادات (رمز الترس في أعلى يسار الصفحة)، وضع علامة في المربّع استخدام بيانات اعتماد OAuth الخاصة بك وأدخِل Client ID وClient secret في الحقول المقابلة، ثم انقر على إغلاق.
  3. ضمن الخطوة 1: اختيار &amp؛ واجهات برمجة التطبيقات وتفويضها، أدخِل نطاق واجهة برمجة التطبيقات https://www.googleapis.com/auth/streetviewpublish في حقل إدخال نطاقاتك الخاصة، ثم انقر على تفويض واجهات برمجة التطبيقات. سيتم فتح صفحة جديدة لتأكيد أنك تريد تفويض واجهة برمجة التطبيقات.
  4. انقر على رمز تفويض Exchange للرموز المميزة. سيؤدي هذا الإجراء إلى تعبئة حقل رمز الدخول الذي يحتوي على رمز الدخول المُستخدَم في الخطوة التالية. ستنتهي صلاحية رمز الدخول خلال 60 دقيقة. يمكنك تحديد خيار إعادة تحميل الرمز المميز تلقائيًا قبل انتهاء صلاحيته، ما سيؤدي إلى إنشاء رمز مميّز جديد.

إرسال طلب HTTP

بعد الحصول على مفتاح واجهة برمجة التطبيقات ورمز الدخول، يمكنك تشغيل الأمر التالي على واجهة أوامر لإجراء استدعاء HTTP للخدمة. في المثال أدناه، نُجري مكالمة مع طريقة /v1/photo:startUpload.

    $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Length: 0'

طلبات نموذجية

بعد إرسال طلب HTTP أعلاه، يمكنك محاولة استخدام بعض الطرق الإضافية. يتم عرض مجموعة متنوعة من المكالمات أدناه.

جارٍ الحصول على قائمة بصورك

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photos?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

جارٍ التقاط صورة

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

تحميل صورة

يتطلب إنشاء صورة ثلاث مكالمات منفصلة. ستعرض المكالمة الأولى عنوان URL للتحميل يُستخدم في المكالمة الثانية لتحميل وحدات بايت الصورة. بعد تحميل وحدات بايت الصورة، تُحمّل المكالمة الثالثة البيانات الوصفية للصورة وتعرض رقم تعريف الصورة.

  1. طلب عنوان URL للتحميل 
            $ curl --request POST \
        --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
        --header 'Content-Length: 0'
  2. حمِّل وحدات بايت الصورة إلى عنوان URL للتحميل. 
            $ curl --request POST \
        --url 'UPLOAD_URL' \
        --upload-file 'PATH_TO_FILE' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  3. حمِّل البيانات الوصفية للصورة. 
            $ curl --request POST \
        --url 'https://streetviewpublish.googleapis.com/v1/photo?key=YOUR_API_KEY' \
        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{
                  "uploadReference":
                  {
                    "uploadUrl": "UPLOAD_URL"
                  },
                  "pose":
                   {
                     "heading": 105.0,
                     "latLngPair":
                     {
                       "latitude": 46.7512623,
                       "longitude": -121.9376983
                     }
                  },
                  "captureTime":
                  {
                    "seconds": 1483202694
                  },
                }'

جارٍ تعديل صورة

   $ curl --request PUT \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY&updateMask=pose.latLngPair' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
               "pose":
               {
                 "latLngPair":
                 {
                   "latitude": 46.7512624,
                   "longitude": -121.9376982
                 }
               }
             }'

تجميع الصور المتعددة

   $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photos:batchUpdate?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
              "updatePhotoRequests": [
                  {
                      "photo": {
                          "photoId": {
                              "id": "FIRST_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1701638,
                                  "longitude": -122.3624387
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  },
                  {
                      "photo": {
                          "photoId": {
                              "id": "SECOND_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1685704,
                                  "longitude": -122.3618021
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  }
              ]
          }'

جارٍ حذف صورة واحدة

    $ curl --request DELETE \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

ما هو updateMask؟

يمكنك استخدام updateMask كطريقة للاحتفاظ بطلباتك صغيرة إذا كنت تريد تعديل جزء من صورتك بدلاً من تعديلها كلها. في حال عدم إضافة updateMask، يؤدي طلبك إلى تعديل الصورة بأكملها. ويعني هذا أنه في حال عدم ضبط updateMask وعدم توفّر طلبك في pose، سيتم محو pose من صورتك. إليك بعض القيم المحتملة للسمة updateMask: places, pose.heading, pose.latlngpair, pose.level, connections. يمكنك وضع القيم المتعددة مفصولة بفواصل في updateMask.