الأغراض المضمّنة (Dialogflow)

النية المضمَّنة هي معرّف فريد يمكنك تحديده لإبلاغ "مساعد Google" بأنّ الإجراء الخاص بك يمكنه تلبية فئة معيّنة من طلبات المستخدمين. على سبيل المثال، إليك بعض الأمثلة على طلبات بحث المستخدمين التي يطابقها "مساعد Google" بالأغراض المضمّنة:

  • الغرض المضمَّن في "تشغيل اللعبة": "Ok Google". تشغيل لعبة ذاكرة"
  • الهدف المضمّن من "الحصول على الأبراج": "Ok Google". معرفة برجي"

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

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

دمج العناصر المضمَّنة

استنادًا إلى كيفية إنشاء الإجراء الخاص بك، هناك طرق مختلفة لدمج الأهداف المضمَّنة.

Dialogflow

إذا كنت تستخدم Dialogflow لإنشاء الإجراء الخاص بك، يمكنك إرفاق هدف مضمّن بشكل بياني من وحدة تحكُّم Dialogflow.

لإرفاق هدف مضمّن باستخدام Dialogflow، اتّبِع الخطوات التالية:

  1. افتح وحدة تحكُّم Dialogflow واختَر الوكيل، ثم انتقِل إلى شاشة Intents.
  2. حدِّد الغرض الذي يشغّله وكيلك أو اختَره عندما يتلقّى هدفًا مضمّنًا محددًا. افتح قسم الأحداث، وانقر على إضافة حدث.

    الشكل 1. إضافة حدث Dialogflow في وحدة تحكُّم Dialogflow.
  3. في حقل الأحداث، اكتب اسم حدث الغرض المضمَّن لوكيلك (على سبيل المثال، actions_intent_PLAY_GAME).

    الشكل 2. إرفاق هدف مضمّن بوكيلك في وحدة تحكّم Dialogflow.
  4. انقر على حفظ.

حزمة تطوير برامج المهام

إذا كنت تستخدم حزمة تطوير البرامج (SDK) للإجراءات لإنشاء الإجراء الخاص بك، عليك تحديد عملية الربط بين الأغراض المضمَّنة والإجراءات في حزمة الإجراءات.

لإرفاق هدف مضمّن باستخدام حزمة تطوير البرامج (SDK) للإجراءات، يمكنك اتّباع الخطوات التالية:

  1. حدد الغرض المضمَّن في حقل الاسم في تعريف الإجراء.
  2. حمِّل حزمة الإجراءات إلى مشروع المهام باستخدام أداة gactions، على النحو الموضّح في نظرة عامة على حزمة تطوير البرامج (SDK) للإجراءات.

على سبيل المثال، يوضّح المقتطف التالي كيفية إضافة هدف CHECK_AIR_QUALITY المضمَّن:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

التعامل مع مَعلمات الأهداف المدمجة

عندما يتم استدعاء الإجراء الخاص بك من خلال هدف مضمَّن، قد يتلقّى تنفيذ الإجراء معلَمات إضافية. ويحدّد مخطط الغرض أسماء المعلَمات وأنواعها كأنواع أساسية أو كيانات على schema.org. لعرض مخطط الأغراض المضمّنة في "الإجراءات القائمة على المحادثة"، راجِع مرجع الأغراض المضمّنة.

معلمات الأغراض المضمنة اختيارية. يتولى "مساعد Google" ملء المعلَمات بقيم إذا كان من الممكن استخراجها من استدعاء المستخدم للهدف المضمَّن.

على سبيل المثال، يحدّد مخطّط الغرض من ميزة actions.intent.CHECK_AIR_QUALITY أربع معلَمات اختيارية:

اسم المعلّمة Type
attributes قيمة سلسلة.
location عنصر schema.org/Place:
temporalCoverage عنصر schema.org/Duration:
timeIndicator EnumeratedDuration (إضافة خاصة بـ Google).

يعرض مقتطف الرمز التالي مثالاً على طلب الرد التلقائي على الويب للمحادثة (JSON) عندما يستدعي مستخدم الإجراء الخاص بك من خلال قول "ما هي جودة الهواء في سان فرانسيسكو غدًا؟":

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

في هذا المثال، تأخذ المعلمات القيم التالية:

  • تحتوي المعلَمة location على القيمة schema.org/Place لـ "سان فرانسيسكو".
  • تحتوي المَعلمة temporalCoverage على القيمة schema.org/Duration لتاريخ الغد مقارنةً بوقت الاستدعاء.
  • ما مِن قيم للمَعلمتَين attributes وtimeIndicator لأن عبارة الاستدعاء التي استخدمها المستخدم لم تتضمّن هذه المعلومات.

إذا كنت تستخدم المهام مع مكتبة عملاء Google لنظام التشغيل Node.js، يمكنك استرداد قيمة المَعلمات كما هو موضّح في المقتطف التالي:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

اختبار عمليات الدمج باستخدام الأغراض المضمّنة

اتّبِع الخطوات التالية لاختبار عملية الدمج:

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

أفضل الممارسات لاستخدام الأغراض المضمّنة

يجب اتّباع أفضل الممارسات التالية عند استخدام الأغراض المضمّنة:

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