يحدّد التنفيذ واجهة المحادثة لمشروع الإجراءات للحصول على مدخلات المستخدمين والمنطق لمعالجة المدخلات وتنفيذ الإجراء في النهاية.
نظرة عامة
تتلقّى الطلبات من "مساعد Google" وتعالج الطلبات وتردّ عليها. تؤدي عملية الطلب والرد المتبادل هذه إلى دفع المحادثة إلى الأمام حتى تلبي في النهاية طلب المستخدم الأولي.
تصف الخطوات التالية كيفية إنشاء عملية التنفيذ باستخدام حزمة تطوير البرامج (SDK) للإجراءات مع Node.js أو مكتبة عملاء Java/Kotlin:
- إعداد كائن ActionsSdkApp
- إنشاء دوال للتعامل مع الطلبات في منطق التنفيذ.
إنشاء مربّعات حوار
إعداد الكائن ActionsSdkApp
يُنشئ الرمز التالي مثيلاً
ActionsSdkApp
ويُجري بعض عمليات إعداد Node.js النموذجية لدوال Google Cloud:
'use strict'; const {actionssdk} = require('actions-on-google'); const functions = require('firebase-functions'); const app = actionssdk({debug: true}); app.intent('actions.intent.MAIN', (conv) => { conv.ask('Hi!'); }); // More intent handling if needed exports.myFunction = functions.https.onRequest(app);
ResponseBuilder responseBuilder = getResponseBuilder(request).add("Hi!"); return responseBuilder.build();
{ "expectUserResponse": true, "expectedInputs": [ { "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "Hi!" } } ] } }, "possibleIntents": [ { "intent": "actions.intent.TEXT" } ] } ], "conversationToken": "{\"data\":{}}", "userStorage": "{\"data\":{}}" }
إنشاء دوال للتعامل مع الطلبات
عندما يقول المستخدمون عبارة معيّنة، ستتلقّى طلبًا من "مساعد Google". لتلبية الأغراض التي تأتي في الطلبات، أنشئ دوال تعالج النية الناتجة.
لمعالجة الطلبات:
نفِّذ أي منطق مطلوب لمعالجة البيانات التي أدخلها المستخدم.
استدعِ الدالة
conv.ask()
لتمرير الاستجابة التي تريد عرضها كوسيطة.
يوضح التعليمة البرمجية التالية كيفية إنشاء رد بسيط:
conv.ask(`Hi! Say something, and I'll repeat it.`);
ResponseBuilder responseBuilder = getResponseBuilder(request).add("Hi! Say something, and I'll repeat it."); return responseBuilder.build();
{ "expectUserResponse": true, "expectedInputs": [ { "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "Hi! Say something, and I'll repeat it." } } ] } }, "possibleIntents": [ { "intent": "actions.intent.TEXT" } ] } ], "conversationToken": "{\"data\":{}}", "userStorage": "{\"data\":{}}" }
معالجة النية
بعد الانتهاء من إعداد جميع الدوال للتعامل مع الأهداف المشغَّلة، استخدِم app.intent
لتعيين المعالِجات للأهداف.
app.intent('actions.intent.TEXT', (conv) => { // handle text intent. }); app.intent('actions.intent.MAIN', (conv) => { // handle main intent. });
@ForIntent("actions.intent.MAIN") public ActionResponse main(ActionRequest request) { // handle main intent // ... } @ForIntent("actions.intent.TEXT") public ActionResponse text(ActionRequest request) { // handle text intent // ... }
إنهاء المحادثات
وإذا لم تعُد تريد أي بيانات يُدخلها المستخدم في المقابل وتريد إنهاء المحادثة،
استدع الدالة conv.close()
.
تطلب هذه الوظيفة من "مساعد Google" قول النص إلى المستخدم وإنهاء المحادثة من خلال إغلاق الميكروفون.
التعامل مع الغرض الرئيسي من الاستدعاء
عندما يشغّل المستخدمون هدف app.intent.action.MAIN
، لن تحتاج عادةً إلى إجراء أي معالجة لإدخالات المستخدمين. إذا كانت حزمة الإجراءات الخاصة بك تحتوي على العديد من الإجراءات
وتغطي العديد من حالات الاستخدام، فمن الجيد توجيه المستخدم من خلال إخباره
ببعض الأشياء التي يمكنه القيام بها.
- استدعِ الدالة
conv.ask()
لتمرير استجابتك كوسيطة. يُعلِم "مساعد Google" المستخدم بردّك ثمّ ينتظر حتى يشغّل المستخدم أحد الأغراض التي حدّدتها.
يوضّح المقتطف التالي كيفية التعامل مع رسالة ترحيب بسيطة:
// handle the initialTrigger function handleMainIntent(conv, input) { conv.ask(input); }
private ActionResponse handleMainIntent(ResponseBuilder rb, String input) { return rb.add(input).build(); }
حالة المحادثة
إذا كنت تستخدم واجهة برمجة تطبيقات الرد التلقائي على الويب الخاصة بـ HTTP/JSON لمحادثة، يمكنك الاحتفاظ
بحالة محادثاتك باستخدام عنصر بتنسيق JSON (conversationToken
) يتم تبادله بينك وبين "مساعد Google". إذا كنت تستخدم مكتبة عميل Node.js، يمكنك الكتابة في الحقل conv.data
والقراءة منه مباشرةً. يتم تمرير هذا الحقل
ذهابًا وإيابًا تلقائيًا بين الطلبات والردود.
conv.data = {something: 10}; let value = conv.data.something;
ResponseBuilder rb = getResponseBuilder(request); rb.getConversationData().put("something", 10); Object value = rb.getConversationData().get("something");