إنشاء مكتبات للعملاء باستخدام Bazelisk (السيارات)

مكتبات العملاء هي واجهات برمجة تطبيقات خاصة بلغة معيّنة. يوضّح هذا المستند كيفية استخدام Bazelisk، مشغّل التطبيقات للغة Bazel، لإنشاء مكتبات عملاء لواجهة Routes API for Automotive بمجموعة متنوعة من لغات البرمجة. يضمن Bazelisk استخدام الإصدار الصحيح من Bazel لتنفيذ أوامر الإصدار.

ويكون الرمز البرمجي اللازم لإنشاء المكتبات مستضافًا في مستودع Gerrit خاص. للحصول على شرح لآلية عمل مكتبات العملاء، يمكنك الاطّلاع على شرح لمكتبات العملاء.

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

متطلبات البرامج

تثبيت ما يلي:

متطلبات الأذونات

  • ويتم توفير الدخول إلى المستودع لأعضاء <partner>@google.com group محددة، يديرها أحد ممثلي شركتك. لإضافتك إلى هذه المجموعة، يرجى التواصل مع جهة التواصل في شركتك أو شريك Google التجاري.

الخطوة 1: الوصول إلى Gerrit

للوصول إلى Gerrit:
  1. تأكَّد من استيفاء متطلبات إذن المستودع الواردة في القسم المتطلبات الأساسية.
  2. أنشِئ حسابًا على Google باستخدام عنوان بريد إلكتروني للشركة من خلال اتّباع التعليمات الواردة في إنشاء حساب Google.
    • عند إنشاء حساب على Google، تأكَّد من عدم تسجيل الدخول إلى gmail.com أو حساب آخر في خدمات نطاقات Google قبل زيارة صفحة "تسجيل الدخول إلى حساب Google". لضمان ملف شخصي نظيف، أغلِق المتصفح وأعِد تشغيله، ثم افتح نافذة تصفُّح متخفٍ (خاص).
    • عند طلب الوصول إلى مستخدمين آخرين، يجب إنشاء حساب لكل فرد يحتاج إلى إذن الوصول. بعد ذلك، أرسل قائمة حسابات Google الجديدة إلى شريكك التجاري في Google. سيضيف شريكك التجاري عناوين البريد الإلكتروني إلى مجموعات الوصول المناسبة.
  3. باستخدام حساب Google الذي أنشأته للتو، انتقِل إلى https://partner-code.googlesource.com. وعند الوصول إلى مضيف Gerrit، سيتم إنشاء مستخدم وتسجيل الدخول إليه تلقائيًا.
  4. من https://partner-code.googlesource.com، انقر على إنشاء كلمة المرور. اتّبِع التعليمات الظاهرة على الشاشة لاختيار حسابك على Google والسماح بالوصول إلى googlesource.com واتّباع التعليمات الأخرى الظاهرة على الشاشة.
  5. عندما يظهر لك نص برمجي، انسخ النص البرمجي والصقه في الوحدة الطرفية.

الخطوة 2: نسخ المستودعات

في هذه الخطوة، سيتم نسخ مستودعات googleapis وroutes-auto-early-access.

  1. استنسِخ مستودع routes-auto-early-access: 
    git clone https://partner-code.googlesource.com/routes-auto-early-access
  2. استنسِخ مستودع Google googleapis العام: 
    git clone https://github.com/googleapis/googleapis.git

الخطوة 3: دمج المستودعات

في هذه الخطوة، سيتم نقل الدليل الفرعي routes-auto-early-access/google/maps/routing/v2 إلى googleapis/google/maps/routing/v2.

  1. بعد استنساخ repos، تأكَّد من أنّ دليل العمل الحالي (pwd) يتضمّن كلاً من الدليلَين الفرعيَين routes-auto-early-access وgoogleapis. 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. أنشئ دليل routing/v2 في الموقع المستهدف وانسخ routing/v2 في googleapis/google/maps/routing/v2: 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

لتأكيد دمج الدليل routing/v2 بنجاح في دليل googleapis/google/maps/routing/v2، انتقِل إلى googleapis/google/maps/routing/v2. يجب أن يحتوي المجلد على ملفات proto وملف BUILD.bazel والملفات الأخرى اللازمة للإصدار.

الخطوة 4: إنشاء مكتبة برامج باستخدام Bazelisk

لإنشاء مكتبة العملاء للغة معيّنة، حدِّد هدف الإصدار لتلك اللغة في ملف BUILD.bazel (في googleapis/google/maps/routing/v2/BUILD.bazel)، ثم أنشئ الهدف المطلوب. يمكنك العثور على الهدف name داخل كائنات <LANGUAGE>_gapic_assembly_pkg. راجع إنشاء هدف واحد في وثائق Bazel لمزيد من المعلومات.

على سبيل المثال، لإنشاء مكتبة عملاء Java، قم بما يلي:

  1. التغيير إلى دليل googleapis: 
    cd googleapis
  2. نفِّذ الطلب التالي: 
    bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java

    يؤدّي هذا الأمر إلى إنشاء مكتبة برامج Java في googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

للتيسير عليك، يسرد الجدول التالي أوامر الإصدار لكل لغة متوفرة.

اللغة أمر إصدار Bazelisk
Java bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-java
البدء bazelisk build google/maps/routing/v2:gapi-cloud-maps-routing-v2-go
PHP bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-php
Ruby bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-ruby
C# bazelisk build google/maps/routing/v2:google-cloud-maps-routing-v2-csharp
العُقدة bazelisk build google/maps/routing/v2:maps-routing-v2-nodejs

دمج التحديثات عند توفُّر إصدارات جديدة

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

  1. انتقِل إلى دليل العمل الحالي الذي يحتوي على المستودعَين: 
    .
   ├── routes-auto-early-access
   └── googleapis
  2. إزالة النسخة الافتراضية السابقة من routing/v2 داخل googleapis/google/maps: 
    rm -rf googleapis/google/maps/routing/v2
  3. يُرجى الانتقال إلى كل من مستودعَي "routes-auto-early-access" و"googleapis" وتشغيل "git pull" للاطّلاع على آخر التعديلات.
  4. نسخ routing/v2 إلى googleapis/google/maps/routing/v2، كما في السابق: 
    mkdir -p "googleapis/google/maps/routing/v2" && cp -R "routes-auto-early-access/google/maps/routing/v2" "googleapis/google/maps/routing"

    لتأكيد دمج مستودع routing/v2 بنجاح في الدليل googleapis/google/maps/routing/v2، انتقِل إلى googleapis/google/maps/routing/v2. يجب أن يحتوي المجلّد على ملفات proto وملف BUILD.bazel والملفات الأخرى اللازمة لإصدار Bazel.

  5. شغِّل أوامر إصدار Bazelisk المدرَجة في القسم السابق الخطوة 4: إنشاء مكتبة برامج باستخدام Bazelisk.

إنشاء مستندات Java لمكتبة برامج Java

تتيح لك مكتبة العملاء إمكانية الاتصال بـ Routes API for Automotive باستخدام الفئات والطرق الخاصة باللغة. لسوء الحظ، لا يتضمن الإخراج وثائق JavaDoc لمكتبة العميل. يوضح هذا القسم كيفية إنشاء JavaDoc لمكتبة عميل Java.

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

لإنشاء Javadoc:

  1. تأكَّد من تثبيت إصدارات متوافقة من Gradle (الإصدار 8.0 أو الإصدارات الأحدث) وJDK (الإصدار 17 أو الإصدارات الأقدم). يمكنك التحقق من الإصدارات المثبّتة من خلال تشغيل ./gradlew --version وjava -version في الوحدة الطرفية.

  2. تم إنشاء مكتبة عملاء Java في ملف tar.gz التالي، والذي ستحتاج إلى استخراجه: googleapis/bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz.

    لنفترض أنّك في دليل googleapis، شغِّل الأمر التالي مع استبدال /PATH/TO/PARENT/DIRECTORY بالمسار الذي اخترته للمكتبة المستخرَجة:

    mkdir -p /PATH/TO/PARENT/DIRECTORY && tar -xzpf bazel-bin/google/maps/routing/v2/google-cloud-maps-routing-v2-java.tar.gz -C /PATH/TO/PARENT/DIRECTORY

  3. انتقِل إلى الدليل الرئيسي:

    cd /PATH/TO/PARENT/DIRECTORY

  4. من دليل google-cloud-maps-routing-v2-java، افتح ملفات build.gradle في كل دليل من الأدلة التالية:

    • gapic-google-cloud-maps-routing-v2-java/build.gradle
    • grpc-google-cloud-maps-routing-v2-java/build.gradle
    • proto-google-cloud-maps-routing-v2-java/build.gradle

    تأكد من أن كل منها يحتوي على المهام التالية. بسبب خطأ، استبدل مهمتين متشابهتين حاليتين بهذا الرمز:

    
task javadocJar(type: Jar, dependsOn: javadoc) {
  archiveClassifier.set('javadoc')
  from javadoc.destinationDir
}

task sourcesJar(type: Jar) {
  archiveClassifier.set('sources')
  from sourceSets.main.allSource
}

artifacts {
archives javadocJar
}

  5. تأكَّد من استخدام الإصدار 8.0 من Gradle أو الإصدارات الأحدث: ./gradlew --version. إذا كان الإصدار 7، عليك إجراء ما يلي: احذف الملفَين gradlew وgradlew.bat من دليل google-cloud-maps-routing-v2-java. بعد ذلك، شغِّل gradle wrapper --gradle-version=8.0 للتبديل إلى الإصدار 8.0.

  6. من دليل google-cloud-maps-routing-v2-java، استخدِم Gradle لإنشاء JavaScript:

    ./gradlew build

    يظهر JavaScript الذي تم إنشاؤه في هذه الأدلة:

    • google-cloud-maps-routing-v2-java/gapic-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/grpc-google-cloud-maps-routing-v2-java/build/docs/javadoc
    • google-cloud-maps-routing-v2-java/proto-google-cloud-maps-routing-v2-java/build/docs/javadoc

  7. افتح ملف overview-tree.html لكل دليل باستخدام متصفِّح ويب.