Özel amaçlar

Her uygulama farklıdır ve tüm uygulama işlevleri mevcut bir Uygulama İşlemleri yerleşik amacı (BII) ile eşleşmez. Uygulamanızın işlevselliği için bir BII'nin bulunmadığı durumlarda, bunun yerine uygulamanızı Uygulama İşlemleri ile genişletmek için özel bir amaç kullanabilirsiniz.

BBI'ler gibi özel amaçlar da shortcuts.xml şemasını takip eder ve Asistan ile tanımladığınız karşılamalar arasındaki bağlantı noktaları olarak görev yapar. Özel amaçlarınız, karşılık gelen istek karşılamanızdaki parametrelerle eşleyebileceğiniz amaç parametrelerine de sahiptir.

Özel amaçlar, BII'lerin aksine, kullanıcının söyleyebileceği örnek sorguları açıklamak için sorgu kalıpları gerektirir. Bu yaklaşım, kullanıcıların söz konusu niyeti ifade etmek için kullandığı yaygın yöntemleri modelleyen yerleşik amaçlardan farklıdır.

Sınırlamalar

Özel amaçlar için aşağıdaki sınırlamalar geçerlidir:

  • Özel amacın adı actions.intent ile başlayamaz.
  • Özel amacın adı, uygulamanızın özel amaç adları arasında benzersiz olmalıdır.
  • Google Asistan tarafından parametre ayıklamak için yalnızca belirli veri türleri kullanılabilir (Desteklenen türler bölümüne bakın).
  • Özel amaçlar, kullanılabilir sorgu kalıpları (bkz. Sorgu kalıpları) içermelidir.
  • Her sorgu en fazla iki metin parametresini destekler. Bu sınır diğer veri türleri için geçerli değildir.
  • Özel amaçlar yalnızca en-US yerel ayarını destekler. Ayrıca cihaz ve Asistan dili ayarları da eşleşmelidir.

Desteklenen türler

Özel amaçlar, parametre ayıklama için aşağıdaki schema.org türlerini destekler:

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

Uygulama İşlemlerini özel amaçlarla tanımlama

BiI kullanan diğer Uygulama İşlemlerinde olduğu gibi shortcuts.xml içindeki <capability> öğesinde özel bir amaç tanımlarsınız.

Özellikler <shortcuts> kök öğesinde tanımlanır. <shortcuts> öğenizi tanımlarken, erişmek istediğiniz özelliklerin ad alanlarını aşağıdaki örnekte gösterildiği gibi ekleyin:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

android:name özelliğinde özel amacın adını sağlayın ve queryPatterns özelliğinde bir sorgu kalıpları kaynak dosyasına referans verin.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Ad alanı BII'lere ayrıldığından özel amaç adları actions.intent ile başlayamaz. Bunun yerine, özel amaçlarınızı adlandırırken özel amaçlarınızı farklı çalışan BBI'lerden ve Android amaçlarından ayırt etmek için custom.actions.intent ön ekini kullanın.

Her parametre için parametrenin anlamını en iyi şekilde açıklayan desteklenen schema.org türünü sağlayın. Örneğin, almayı beklediğiniz bir tarihi belirtmek için https://schema.org/Date ifadesini kullanabilirsiniz:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

shortcuts.xml dilindeki özel amaçlar için kısayolları, BiI'ların kısayollarıyla aynı biçimi kullanarak tanımlayın.

Aşağıdaki kodda SCHEDULE_APPOINTMENT özel amacını tetiklemek üzere başvurulan sorgu kalıplarını kullanan ve apptType parametresi için tanımlı bir grup değer (DRIVERS_LICENSE ve VEHICLE_REGISTRATION) kullanan bir Uygulama İşlemi açıklanmaktadır.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

Özel amaç parametrelerini satır içi envanter ile yapılandırabilirsiniz. Bunu, varlık çıkarmayı shortcuts.xml politikasında belirtilen desteklenen bir grup varlık grubuna yönlendirmek için kullanabilirsiniz.

Sorgu kalıpları

Kullandığınız her özel amaç, söz konusu amaç için kullanıcıdan beklenen bir sorgu kümesi gerektirir. Bu yaklaşım, sorguların kullanıcıların yapmaya çalıştıkları görevleri veya aradıkları bilgileri ifade ettikleri yaygın yöntemlere göre modellendiği BBI'lerden farklıdır.

Bir Android kaynak dosyasında (genellikle /res/values/strings.xml), sorgu kalıplarını dize dizisi içindeki öğeler olarak belirtin. Uygulama İşleminiz çağrıldığında Google Asistan, kullanıcının istek karşılama niyetini eşleştirmenin bir parçası olarak kullanıcı sorgusunu sorgu kalıplarınızla karşılaştırarak kontrol eder. Sağladığınız her sorgu kalıbı, ilgili özel amaç için geçerli olduğunu düşündüğünüz bir kelime öbeğini temsil eder.

Özel amaçlar için sorgu kalıpları sağlarken her bir kalıbın "Örnek Uygulamayı aç" veya "Örnek Uygulamayı başlat ve" gibi açık bir çağrıyı takip etmesini bekleyin. Örneğin, aşağıdaki kullanıcı sorgularını göz önünde bulundurun:

  • "Ok Google, Örnek Oyun Uygulaması'nı aç ve pasta yapmaya başla."
  • "Ok Google, Örnek Oyun Uygulaması'nı aç ve elmalı turta yapmaya başla."
  • "Ok Google, Örnek Oyun Uygulaması'nı başlat ve 5 pasta yap."
  • "Ok Google, Örnek Oyun Uygulaması'nı kullanarak 5 kez pasta üretiyorum."

Kullanıcı sorgularını eşleştirmek için sorgunun çağrı ifadesinden sonraki bölümünü içeren sorgu kalıpları sağlayın. Sorgudan çıkarmak istediğiniz bilgiler (metin veya kullanıcı tarafından sağlanan bir sayı gibi) için ilgili intent parametresine sorgu kalıbında yer tutucularla birlikte değerler atarsınız.

Sorgu kalıbındaki bir parametreye referans vermek için kalıbınızdaki parametrenin adına $ ekleyin. Örneğin, <parameter name="date1" ... (actions.xml içinde) veya <parameter android:name="date1" ... (shortcuts.xml) gibi bir parametre için yer tutucu değeri oluşturmak üzere $date1 kullanırsınız.

Aşağıdaki kod, önceki kullanıcı sorgularıyla eşleşen sorgu kalıplarını ve öğe adları ve yapılacak öğe sayısı için değerleri ayıklar:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Sorgu kalıpları koşulları destekler. Örneğin, set (an)? appointment $date $time. Bu durumda hem "bugün öğlen randevu ayarla" hem de "bugün öğlen randevu ayarla" geçerli sorgulardır.