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

إجراء طلبات HTTP

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

وتتوفر أيضًا بعض مكتبات البرامج في حال عدم توفّرها يريدون إجراء اتصالات HTTP مباشرة.

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

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

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

3. بعد إنشاء مشروعك، تأكَّد من أنّ واجهة Street View Publish API هي إحدى الخدمات التي تم تسجيل تطبيقك لاستخدامها:

   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: تحديد & تفويض واجهات برمجة التطبيقات، أدخِل نطاق واجهة برمجة التطبيقات 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.