إنشاء المشاريع

يحزم مشروع الإجراءات جميع الإجراءات في حاوية واحدة. عليك نشر هذا المشروع إلى "المهام مع مساعد Google" ليتمكّن "مساعد Google" من التعرّف على كيفية استكشاف تجاربك في المحادثات واستدعاءها.

مكونات مشروع الإجراءات
الشكل 1. بنية مشروع الإجراءات

يمكنك استخدام المكوّنات المنخفضة المستوى التالية لإنشاء مشروع Actions (الإجراءات):

  • تحدد الإعدادات والموارد البيانات الوصفية للمشروع والموارد مثل أيقونات المشروع. تستخدم Google هذه المعلومات لنشر الإجراءات الخاصة بك على دليل "مساعد Google" ليتمكّن المستخدمون من اكتشافها واستدعاءها.

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

  • تتيح لك الأنواع استخراج البيانات المنظَّمة من البيانات التي أدخلها المستخدم. ومن خلال إضافة تعليقات توضيحية إلى عبارات التدريب باستخدام الأنواع، يمكن لوحدة NLU استخراج البيانات المنظَّمة ذات الصلة بك، حتى لا تضطر إلى تحليل الإدخالات المفتوحة.

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

  • تحدِّد الطلبات الردود الثابتة أو الديناميكية التي تستخدِمها للردّ على المستخدمين.

  • تتيح لك الردود التلقائية على الويب تفويض العمل الإضافي لخدمات الويب (تنفيذ الإجراء)، مثل التحقّق من صحة البيانات أو إنشاء طلبات. تتواصل الإجراءات الخاصة بك مع عملية التنفيذ من خلال بروتوكول الردّ التلقائي على الويب المستند إلى JSON.

  • تتيح لك لوحة الرسم التفاعلية إنشاء تجارب غنية وغامرة مع تطبيقات الويب التي تستخدم HTML وCSS وJavaScript.

إنشاء مشروع

يجب إنشاء مشروع في وحدة تحكّم المهام قبل أن تتمكّن من تطويره باستخدام "مساعد Google". لإنشاء مشروع:

  1. انتقِل إلى وحدة تحكّم "الإجراءات".
  2. انقر على مشروع جديد.
  3. أدخِل اسمًا لمشروعك وانقر على إنشاء مشروع.
  4. في الشاشة ما نوع الإجراء الذي تريد إنشاءه؟، اختَر فئة تمثل مشروعك على أفضل وجه وانقر على التالي.
  5. في شاشة طريقة الإنشاء، اختَر طريقة للإنشاء وانقر على بدء الإنشاء. على سبيل المثال، يمكنك البدء بمشروع فارغ أو عيّنة.

إنشاء مشروع حزمة تطوير برامج (SDK) محلي

بعد إنشاء مشروع "المهام" في وحدة تحكُّم "المهام"، يمكنك إعداد مشروع في بيئة التطوير المحلية.

لإعداد مشروع SDK لـ Actions من مشروع حالي في Actions (المهام)، يُرجى اتّباع الخطوات التالية:

  1. أنشئ دليلاً فارغًا لمشروع "المهام" على نظام الملفات المحلي.
  2. في هذا الدليل الفارغ، يمكنك إنشاء دليل sdk.
  3. عليك تغيير دليل العمل إلى الدليل sdk في الوحدة الطرفية.

البدء بمشروع فارغ

إذا أردت البدء من المشروع الفارغ الذي أنشأته للتو في وحدة التحكّم، شغِّل gactions pull --project-id <my-project-id>. 

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

البدء بنموذج مشروع

إذا كنت تريد البدء من نموذج مشروع، شغِّل gactions init <sample name>. 

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

تحديد معلومات المشروع

تحدد إعدادات المشروع وموارده معلومات حول مشروعك مثل دعم الميزات والمساحات، واللغات المحلية المتوافقة، والاسم المعروض، والوصف، والشعارات، وغير ذلك. يصف الجدول التالي الإعدادات والموارد الرئيسية التي تقدمها. ويستخدم "المهام مع مساعد Google" هذه المعلومات لنشر مشروعك على دليل مساعد Google.

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

لتحديد معلومات المشروع:

  1. يمكنك تحديد الإعدادات العامة لمشروع الإجراءات في sdk/settings/settings.yaml. راجع الوثائق المرجعية للإعدادات للقيم المسموح بها.

    يعرض المقتطف التالي مثالاً لملف sdk/settings/settings.yaml: 

    accountLinking:
  enableAccountCreation: true
  linkingType: GOOGLE_SIGN_IN
category: GAMES_AND_TRIVIA
projectId: my-project-id
...

  2. حدِّد الإعدادات التي يمكن أن تختلف استنادًا إلى لغة المستخدم (على سبيل المثال، عبارات الاستدعاء بلغات مختلفة) في ملف sdk/settings/<locale>/settings.yaml، مع استبدال اللغة باللغة الهدف.

    راجِع الوثائق المرجعية LocalizedSettings لمعرفة القيم المسموح بها.

    المقتطف التالي هو مثال على إعدادات اللغة الإنجليزية المحدّدة في ملف sdk/settings/en/settings.yaml:

    localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action
  largeBannerImage: https://path/to/large/banner
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action
  smallLogoImage: https://path/to/small/logo
  voice: female_1
...

إضافة مراجع

يمكنك تخزين موارد مثل ملفات الصور وملفات الصوت والسلاسل في مشروع المهام والإشارة إليها من ملفات الإعداد (مثل تعريفات الطلبات أو شروطها) باستخدام المتغيّر $resources المحدّد من خلال النظام.

يتم تخزين موارد المشروع ضمن resources/، ويتم تخصيص مجلد في الدليل لكل نوع مورد.

يمكنك ترجمة الموارد من خلال إنشاء مجلدات حسب اللغة في مجلد نوع الموارد، على سبيل المثال يمكنك تخزين الإصدارات الإسبانية من السلاسل في resources/strings/es/<filename>.yaml.

الصور

يتم تخزين ملفات الصور في resources/images/، ويمكنك الرجوع إليها باستخدام $resources.images.<name of the image file without file extension>. امتدادات الملفات المسموح بها هي:

  • gif
  • png
  • jpg
  • jpeg

على سبيل المثال، إذا تم حفظ النسخة الإنجليزية من الشعار الصغير في resources/images/en/square.png والنسخة الإنجليزية من إعلان البانر الكبير في resources/images/en/landscape.jpg على التوالي، سيصبح sdk/settings/en/settings.yaml من المثال السابق:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

ملفات صوتية

يتم تخزين الملفات الصوتية في resources/audio/، ويمكنك الرجوع إليها باستخدام $resources.audio.<name of the audio file without file extension>.

امتدادات الملفات المسموح بها هي:

  • mp3
  • mpeg

على سبيل المثال، يمكنك الإشارة إلى تسجيلات صوتية من الطلبات:

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

السلاسل

يتم تخزين السلاسل في resources/strings/ كملفات .yaml. يحتوي كل ملف على خريطة لمفاتيح السلسلة والقيم المرتبطة بها، والتي يمكن أن تكون سلاسل مفردة أو قوائم من السلاسل. يمكنك الإشارة إلى القيم باستخدام $resources.strings.<name of the image file without file extension>.<key> لقيم سلسلة فردية أو الحصول على قيمة عشوائية من قائمة، و$resources.strings.<name of the image file without file extension>.<key>.<numerical index> لقيمة سلسلة معيّنة في قائمة.

على سبيل المثال، باستخدام سلاسل الموارد لأقلمة السلاسل، يمكن أن يصبح sdk/settings/en/settings.yaml من المثال السابق:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

اختبار المشاريع في المحاكي

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

الشكل 3. المناطق الرئيسية للمحاكي: (1) إدخال المستخدم و(2) عرض الجهاز و(3) الخيارات والإعدادات و (4) سجلّ المحادثات.

لاختبار مشروع:

  1. شغِّل gactions deploy preview لنشر الإجراء على "المعاينة" وتفعيل الاختبار في المحاكي.
  2. افتح عنوان URL في مخرجات الأمر للوصول إلى المحاكي.
$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview