إعداد ميزة "التنقل المتصل"

المطوّرون في المنطقة الاقتصادية الأوروبية

يصف هذا المستند الخطوات التي يجب اتّباعها لبدء استخدام Navigation Connect.

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

يوضّح هذا الدليل كيفية إعداد حسابك على Google Cloud ومشروعك على السحابة الإلكترونية مع تفعيل الفوترة. يجب أيضًا أن تكون على دراية بكيفية تحصيل الرسوم منك مقابل استخدام Navigation Connect API.

  1. راجِع الفوترة وتكلفة الاستخدام في استخدام Navigation Connect والفوترة.
  2. تأكَّد من أنّ لديك حساب على Google Cloud.

    تسجيل الدخول إلى Google Cloud Console
  3. تأكَّد من أنّ لديك مشروعًا على Google Cloud تم تفعيل الفوترة فيه.

    الانتقال إلى صفحة "الفوترة"
    1. اختَر مشروعك لفتح صفحة الفوترة.
    2. في صفحة الفوترة:

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

تفعيل واجهة برمجة التطبيقات والتحقّق من تطبيقك

يصف هذا الدليل عملية تفعيل Navigation Connect API والتحقّق من تطبيقك في Google Cloud Console، ما يتيح لتطبيقك التفاعل بأمان مع "خرائط Google" وWaze. يجب إكمال هذه العملية لاستخدام Navigation Connect API.

1. تفعيل Navigation Connect API

استخدِم وحدة تحكّم Google Cloud أو الأمر gcloud لتفعيل واجهة Navigation Connect API في مشروعك على السحابة الإلكترونية.

لتفعيل واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

وحدة التحكّم

  1. افتح صفحة المنتج في Google Cloud Console:

    تفعيل Navigation Connect API
  2. يمكنك النقر على الزر تمكين.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "navigationconnect.googleapis.com"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

2. بدء عملية التحقّق من التطبيق

بعد تفعيل واجهة برمجة التطبيقات، عليك التحقّق من تطبيقك لتفعيل Navigation Connect API. لا يمنح تفعيل واجهة برمجة التطبيقات وحدها إذن الوصول، بل يجب تقديم تفاصيل النشاط التجاري والتطبيق لمراجعتها قبل أن تتمكّن من استخدام Navigation Connect API.

لبدء عملية التحقّق، استخدِم إحدى الطريقتين التاليتين:

  • سوق واجهات برمجة التطبيقات:
    1. في API Marketplace، ابحث عن بطاقة Navigation Connect API.
    2. انقر على الرمز الأزرق مطلوب إثبات الهوية لبدء عملية إثبات الهوية.
  • المفاتيح وبيانات الاعتماد في Google Cloud Console:
    1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة المفاتيح وبيانات الاعتماد.
    2. انقر على مفاتيح وبيانات اعتماد Navigation Connect.
    3. في البانر، انقر على بدء عملية التحقّق.

3- تقديم تفاصيل عن التطبيق وجمع البيانات والخصوصية

يوضّح الجدول التالي التفاصيل التي يجب تقديمها للتحقّق من التطبيق:

الحقل الوصف
تفاصيل التطبيق

يُرجى تقديم التفاصيل التالية لضمان عرض تطبيقك بشكل صحيح في "خرائط Google" وWaze.

اسم المؤسسة أو التطبيق أدخِل الاسم الذي سيظهر للمستخدمين في "خرائط Google" وWaze.
معرّف التطبيق أدخِل اسم حزمة Android أو معرّف حزمة iOS.
رابط iOS العام قدِّم الرابط العام لنظام التشغيل iOS الذي يسمح للمستخدمين بالعودة إلى تطبيقك (متاح على Waze فقط).
شعار التطبيق (Waze فقط) (اختياري) حمِّل شعارًا بتنسيق PNG أو JPG (من 32×32 إلى 128×128 بكسل) لعرض شعار تطبيقك في Waze أثناء جلسة التنقّل.
تفاصيل حول جمع البيانات والخصوصية

أدخِل التفاصيل التالية لضمان الشفافية وثقة السائقين وأمان البيانات.

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

4. المراجعة والإرسال

راجِع ملخّص المعلومات التي قدّمتها قبل إرسال تطبيقك للتحقّق منه.

  1. راجِع بعناية اسم تطبيقك والنظام الأساسي وأرقام التعريف والروابط.

  2. ضَع علامة في مربّع الاختيار جميع المعلومات دقيقة.
  3. انقر على إرسال.

بعد إرسال تطبيقك للتحقّق منه، تبدأ مرحلة المراجعة.

  • الجدول الزمني: تستغرق عملية التحقّق عادةً من يوم إلى 3 أيام عمل.
  • الإشعار: ستتلقّى رسالة إلكترونية عند تغيير حالة التحقّق. ستصلك أيضًا رسالة إلكترونية تطلب منك معرّف ملف الدفع أو معرّف مطوّر برامج Android. إذا كنت بحاجة إلى معرّف مطوّر برامج Android، يُرجى الاطّلاع على إنشاء حساب مطوّر.
  • تتبُّع الحالة: يمكنك مراقبة مستوى تقدّمك في صفحة المفاتيح وبيانات الاعتماد في Google Cloud Console.
  • الدعم: لتعديل الإعدادات بعد الموافقة بدون التأثير في الإنتاج، يمكنك إنشاء طلب دعم.

بعد إثبات صحة تطبيقك، سيتم السماح له باستخدام Navigation Connect API لإنشاء رموز مميّزة للرحلات تسمح بالوصول إلى جلسة تنقّل وتتيح لك تلقّي تفاصيل الرحلة من "خرائط Google" وWaze.

تتطلّب منتجات "منصة خرائط Google" أن تتضمّن طلبات البيانات من واجهة برمجة التطبيقات رمز OAuth مميّزًا لمنع الاستخدام غير المصرّح به.

إنشاء رمز OAuth مميّز

يتيح Navigation Connect استخدام بروتوكول OAuth 2.0 للمصادقة. تتيح Google سيناريوهات OAuth 2.0 الشائعة، مثل سيناريوهات خادم الويب.

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

يمكنك طلب بيانات من Google Maps API مباشرةً من خلال إرسال طلبات بيانات من واجهة برمجة التطبيقات إلى الخادم، أو يمكنك استخدام مكتبات العملاء لتبسيط الرمز البرمجي. توفّر "خرائط Google" مكتبات برامج للغات Go وJava وNode.js وPython. لمزيد من المعلومات، يُرجى الاطّلاع على مكتبات عملاء Navigation Connect.

نظرة عامة على OAuth

يمكنك إنشاء رموز الدخول وإدارتها باستخدام OAuth بعدة طرق حسب بيئة النشر.

يمكنك استخدام OAuth 2.0 للتفاعلات بين الخوادم بين تطبيقك وخدمة Google. في هذا السيناريو، يمكنك استخدام حساب خدمة مرتبط بتطبيقك بدلاً من مستخدم فردي. يمكنك إرسال طلبات بيانات من واجهة برمجة التطبيقات باستخدام حساب الخدمة بدون إشراك المستخدمين مباشرةً. لمزيد من المعلومات عن طرق المصادقة، يُرجى الاطّلاع على طرق المصادقة في Google.

بدلاً من ذلك، يمكنك دمج Navigation Connect في تطبيق متوافق مع Android أو iOS. لمزيد من المعلومات حول استخدام OAuth وإدارة رموز الدخول لبيئات النشر المختلفة، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

نطاقات OAuth

لاستخدام OAuth مع Navigation Connect، يجب منح رمز OAuth المميز النطاق التالي:

https://www.googleapis.com/auth/cloud-platform

مثال: تجربة طلبات بيانات من واجهة برمجة التطبيقات REST API في بيئة التطوير المحلية

إذا لم تكن لديك بيئة تنشئ الرموز المميّزة وأردت تجربة Navigation Connect باستخدام رمز OAuth مميّز، اتّبِع الإجراءات الواردة في هذا القسم.

يوضّح هذا المثال كيفية استخدام رمز OAuth المميّز الذي توفّره بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الطلب. لمزيد من المعلومات حول استخدام ADC لطلب Google APIs من خلال مكتبات العملاء، يُرجى الاطّلاع على المصادقة باستخدام مكتبات العملاء.

استخدِم إجراء REST التالي لأغراض التطوير أو الاختبار فقط، وليس لأغراض الإنتاج.

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

قبل إجراء طلب REST باستخدام ADC، استخدِم واجهة سطر الأوامر (CLI) في gcloud لتقديم بيانات الاعتماد إلى ADC:

  1. ثبِّت واجهة سطر الأوامر (CLI) في gcloud وافتحها. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تثبيت gcloud CLI.

  2. المصادقة باستخدام واجهة سطر الأوامر (CLI) في gcloud:

    gcloud auth application-default login
  3. أكمِل عملية تسجيل الدخول لحفظ بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه ADC.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد ADC لبيئة تطوير محلية.

إرسال طلب REST

في هذا المثال، يتم تمرير عنوانَي طلب:

  • مرِّر رمز OAuth المميّز في العنوان Authorization باستخدام الأمر التالي لإنشاء الرمز المميّز:

    gcloud auth application-default print-access-token

    يحتوي الرمز المميّز الذي تم إرجاعه على نطاق https://www.googleapis.com/auth/cloud-platform.

  • أدخِل رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في العنوان X-Goog-User-Project.

لاستدعاء Navigation Connect باستخدام رمز OAuth المميّز، أكمِل الخطوات التالية:

  1. في عينة التعليمات البرمجية التالية، استبدِل العناصر النائبة بقيمك:

    • ‫PROJECT_ID: رقم تعريف مشروعك على Google Cloud
    • ‫ANDROID_APP_ID: اسم حزمة Android لتطبيقك، إن وُجد
    • ‫IOS_APP_ID: معرِّف حزمة iOS لتطبيقك، إن توفّر
    #!/bin/bash
    trip_id="$(uuidgen)"
    access_token="$(gcloud auth application-default print-access-token)"
    curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
    -H "Authorization: Bearer ${access_token}" \
    -H "Content-Type: application/json" \
    -d '{
    "androidAppId": "ANDROID_APP_ID",
    "iosAppId": "IOS_APP_ID",
    }'
  2. لنسخ الأمر curl، انقر على نسخ في عينة التعليمات البرمجية.

  3. الصِق الأمر في نافذة المحطة الطرفية، ثم شغِّله.

الردّ هو عنصر JSON:

{
  "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z",
}

يتضمّن هذا الردّ القيم التالية:

  • ‫PROJECT_NUMBER: المعرّف الفريد للمشروع الذي يتألف من عدد صحيح طويل
  • ‫TRIP_ID: معرّف الرحلة UUIDv4 الذي تنشئه الواجهة الخلفية
  • ‫BASE64_ENCODED_TRIP_TOKEN: الرمز المميّز الذي تمت مصادقته والذي تعرضه طريقة createTrip لبدء الاتجاهات المفصّلة التي يتم تتبّعها في "خرائط Google" أو Waze

تحديد المشاكل وحلّها

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

الخطوات التالية

بعد ذلك، عليك ضبط حسابات الخدمة في Navigation Connect API لإتاحة الاتصال الآمن بين الخوادم في البنية الأساسية الخلفية و"خرائط Google" وWaze.

إعداد حساب الخدمة