Yerleşik amaçlar (Dialogflow)

Yerleşik intent, Google Asistan'a İşleminizin belirli bir kullanıcı isteği kategorisini yerine getirebileceğini bildirmek için belirtebileceğiniz benzersiz bir tanımlayıcıdır. Örneğin, Asistan'ın yerleşik amaçlarla eşleştirdiği kullanıcı sorgusu örneklerini aşağıda görebilirsiniz:

  • "Oyun oyna" yerleşik amacı: "Ok Google. Hafıza oyunu oynayın"
  • "Burç al'ın yerleşik amacı: "Ok Google. Yıldız falımı göster"

İşlem keşfi sırasında Asistan, kullanıcılara İşleminizi önermek için, belirttiğiniz yerleşik amaçlar da dahil olmak üzere İşleminizle ilgili meta verileri kullanabilir. Asistan, konuşmalardaki gidiş dönüşleri en aza indirmek için kullanıcı sorgularındaki parametreleri taramaya ve bunları İşleminize aktarmaya da çalışır.

Asistan'ın desteklediği yerleşik amaçların tam listesini (parametreleri ve örnek kullanıcı sorguları dahil) görmek için Yerleşik amaçlar referansına bakın.

Yerleşik amaçları entegre edin

İşleminizi nasıl oluşturduğunuza bağlı olarak, yerleşik amaçları entegre etmenin farklı yolları vardır.

Dialogflow

İşleminizi oluşturmak için Dialogflow kullanıyorsanız Dialogflow konsolundan grafik olarak yerleşik bir intent ekleyebilirsiniz.

Dialogflow ile dahili niyet eklemek için aşağıdaki adımları uygulayın:

  1. Dialogflow konsolunu açın, aracınızı seçin, ardından Intents (Amaçlar) ekranına gidin.

  2. Aracınızın belirli bir yerleşik amaç aldığında tetiklediği amacı oluşturun veya seçin. Etkinlikler bölümünü açın ve Etkinlik Ekle'yi tıklayın.

    Şekil 1. Dialogflow konsoluna Dialogflow etkinliği ekleme.

  3. Etkinlikler alanına, aracınız için bir yerleşik amaç etkinliğinin adını yazın (örneğin, actions_intent_PLAY_GAME).

    Şekil 2. Dialogflow konsolunda aracınıza yerleşik intent ekleme.

  4. Kaydet'i tıklayın.

Actions SDK

İşleminizi oluşturmak için Actions SDK'sını kullanıyorsanız yerleşik amaçlar ile Action paketinizdeki Actions arasındaki eşlemeyi belirtmeniz gerekir.

Actions SDK'sı ile yerleşik bir amaç eklemek için şu adımları uygulayın:

  1. Yerleşik amacı, İşlem tanımınızdaki ad alanında belirtin.
  2. Actions SDK'ya genel bakış bölümünde açıklandığı gibi gactions aracını kullanarak işlem paketinizi Actions projenize yükleyin.

Örneğin, aşağıdaki snippet'te CHECK_AIR_QUALITY yerleşik amacını nasıl ekleyebileceğinizi görebilirsiniz:

{
   "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
      }
   }
}

Yerleşik intent parametrelerini işleyin

İşleminiz yerleşik bir amaç aracılığıyla çağrıldığında, karşılamanız ek parametreler alabilir. Amaç şeması, parametrelerin adlarını ve türlerini temel türler veya schema.org varlıkları olarak tanımlar. Conversational Action yerleşik intent'lerine yönelik şemayı görüntülemek için Yerleşik intentler referansına bakın.

Yerleşik intent parametreleri isteğe bağlıdır. Asistan, parametrelerin kullanıcının yerleşik intent çağrısından çıkarılabildiği durumlarda değerlerle doldurulur.

Örneğin, yerleşik actions.intent.CHECK_AIR_QUALITY amacının şeması dört isteğe bağlı parametre tanımlar:

Parametre Adı Tür
attributes Dize değeri.
location schema.org/Place nesnesi.
temporalCoverage schema.org/Duration nesnesi.
timeIndicator EnumeratedDuration (Google'a özel uzantı).

Aşağıdaki kod snippet'inde, bir kullanıcı "What's the air Quality in San Francisco?" (Yarın San Francisco'da hava kalitesi nasıl olacak?) diyerek İşleminizi çağırdığında gerçekleşen görüşme webhook'u (JSON) isteğine ilişkin bir örnek gösterilmektedir:

"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"
            }
         ]
      }
   ]

Bu örnekte, parametreler aşağıdaki değerleri alır:

  • location parametresi, "San Francisco" için schema.org/Place değerini içerir.
  • temporalCoverage parametresi, yarının tarihinin çağrı zamanına göre schema.org/Duration değerini içerir.
  • Kullanıcının çağrı ifadesi bu tür bilgileri içermediğinden attributes ve timeIndicator parametreleri için değer yoktur.

Node.js için Google İstemci Kitaplığı'nda İşlemler'i kullanırsanız parametrelerin değerini aşağıdaki snippet'te gösterildiği gibi alabilirsiniz:

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.

});

Yerleşik intent'lerle entegrasyonları test etme

Entegrasyonunuzu test etmek için aşağıdaki adımları uygulayın:

  1. İşlem simülatörünü test İşleminiz etkin durumdayken açın veya cihazınızda Asistan'ı açın.
  2. Söz konusu yerleşik intent ile ilişkili bir sorguyu söyleyin veya yazın. Örneğin, "Oyun oynamak istiyorum."
  3. Görüntülenen uygulama seçimi iletişim kutusunda İşleminizi bulun.
  4. Uygulamanıza niyet göndermek için uygulamanızı seçin.
Şekil 3.
Yerleşik bir amaç ifadesinden
oluşan İşlem seçimi iletişim kutusu.
Şekil 4. Yerleşik bir amaca bağlı bir İşlem'i çağırma.

Yerleşik amaçların kullanımıyla ilgili en iyi uygulamalar

Yerleşik amaçları kullanırken aşağıdaki en iyi uygulamaları izlemelisiniz:

  • Yerleşik amaçları belirli işlemlerle eşleştirin: Belirli bir yerleşik amaç İşleminizi tetiklediğinde kullanıcıyı olabildiğince az çaba göstererek İşleminizdeki belirli amaca ve işleve yönlendirin. Örneğin, İşleminiz PLAY_GAME yerleşik amacını destekliyorsa ve bu amacı alırsa kullanıcıyı hemen İşleminizin oyun özelliğine göndermeniz gerekir. Kullanıcıya oyun oynamak isteyip istemediğini tekrar sormaktan kaçının.
  • Yerleşik amaç parametrelerini işleme: Asistan'ın istek karşılama mantığınıza gönderdiği yerleşik amaç parametresi değerlerini kullandığınızdan emin olun. Bu değerleri kullanıcıya tekrar istemekten kaçının.