プロジェクトをビルドする

Actions プロジェクトは、すべてのアクションを 1 つのコンテナにパッケージ化します。このプロジェクトを Actions on Google に公開すると、Google アシスタントが会話エクスペリエンスの検出方法と呼び出し方法を認識できるようになります。

Actions プロジェクトのコンポーネント
図 1. Actions プロジェクトの構造

Actions プロジェクトを作成するには、次の低レベル コンポーネントを使用します。

  • 設定とリソース。プロジェクト メタデータと、プロジェクト アイコンなどのリソースを定義します。Google はこの情報を使用してアクションをアシスタント ディレクトリに公開し、ユーザーがアクションを見つけて呼び出せるようにします。

  • インテントは、ユーザー入力や処理が必要なシステム イベントなど、実行されるタスクを表します。最も一般的なタイプのインテントは、ユーザー インテントです。これらのインテントを使用すると、NLU（自然言語理解）エンジンによって自然に拡張され、さらに多くの類似のフレーズを含むトレーニング フレーズを宣言できます。NLU はこれらのフレーズの集約を使用して、アシスタントがユーザー入力との照合に使用する言語モデルをトレーニングします。会話中にユーザー入力がインテントの言語モデルと一致すると、アシスタント ランタイムはインテントをアクションに送信します。これにより、アクションはアクションを処理してユーザーに応答できます。

  • 型を使用すると、ユーザー入力から構造化データを抽出できます。トレーニング フレーズに型アノテーションを付けることで、NLU が関連する構造化データを抽出できるため、自由記述形式の入力を解析する必要がなくなります。

  • シーンはインテントを処理し、アクションのメインロジック エグゼキュータです。スロットフィルの実行、条件付きロジックの評価、ユーザーにプロンプトの表示を行えます。さらに、外部ウェブサービスを呼び出してビジネス ロジックを実行することもできます。シーンをインテントと組み合わせて使用すると、特定のユーザー入力やシステム イベントを検出し、対応するロジックを実行できます。

  • プロンプトは、ユーザーに返信するために使用される静的または動的なレスポンスを定義します。

  • Webhook を使用すると、データの検証やプロンプトの生成などの追加の作業をウェブサービス（フルフィルメント）に委任できます。アクションは、JSON ベースの Webhook プロトコルを介してフルフィルメントと通信します。

  • Interactive Canvas を使用すると、HTML、CSS、JavaScript を活用したウェブアプリで、豊かで臨場感のあるエクスペリエンスを作成できます。

プロジェクトを作成する

Google アシスタント向けの開発を行うには、Actions Console でプロジェクトを作成する必要があります。プロジェクトを作成するには:

  1. Actions Console に移動します。
  2. [New project]（新しいプロジェクト）をクリックします。
  3. プロジェクトの名前を入力し、[プロジェクトを作成] をクリックします。
  4. [What kind of Action do you want to build?]（アクションの種類を選んでください）画面で、プロジェクトに最も適したカテゴリを選択し、[Next] をクリックします。
  5. [How do you want to build it] 画面でビルド方法を選択して、[Start building] をクリックします。たとえば、空のプロジェクトやサンプルで始めることができます。

ローカルの Actions SDK プロジェクトを作成する

Actions Console で Actions プロジェクトを作成したら、ローカル開発環境でプロジェクトを初期化できます。

既存の Actions プロジェクトから Actions SDK プロジェクトを初期化する手順は次のとおりです。

  1. ローカル ファイル システムに Actions プロジェクト用の空のディレクトリを作成します。
  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.

プロジェクト情報を定義する

プロジェクトの設定とリソースでは、機能とサーフェスのサポート、サポートされているロケール、表示名、説明、ロゴなど、プロジェクトに関する情報を定義します。次の表に、指定する主な設定とリソースを示します。Actions on Google は、この情報を使用してプロジェクトをデプロイし、アシスタント ディレクトリに公開します。

名前 説明
ディレクトリの情報 Actions on Google がアシスタント ディレクトリにプロジェクトを公開するための情報を提供します。プロジェクトに関するメタデータと説明、ロゴとバナー画像の画像リソースが含まれます。
地域ターゲティング アクションを使用できるロケールを設定します。
サーフェス機能 アクションを使用できるサーフェスを構成します。
会社情報 会社の連絡先情報を指定します。
ブランドの確認 所有するウェブサイトまたは Android アプリを接続すると、予約済みの呼び出し名やウェブサイト リンクなどの追加機能をアクション内で使用できます。
リリース アクションをテスト環境と本番環境用に、異なるテスト版リリースと製品版リリースを構成します。
アシスタント リンク ユーザーがウェブ プロパティからアクションを呼び出せるようにします。

プロジェクト情報を定義するには:

  1. sdk/settings/settings.yaml で Actions プロジェクトのグローバル設定を定義します。サポートされている値については、設定のリファレンス ドキュメントをご覧ください。

    次のスニペットは、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 ファイルで定義し、locale を対象のロケールに置き換えます。

    サポートされている値については、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
...

リソースを追加

Actions プロジェクトに画像ファイル、音声ファイル、文字列などのリソースを保存し、システム定義の $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

文字列

文字列は .yaml ファイルとして resources/strings/ に保存されます。各ファイルには、文字列キーと関連する値のマップ（単一の文字列または文字列のリスト）が含まれています。単一の文字列値に $resources.strings.<name of the image file without file extension>.<key> を使用するか、リストからランダム値を取得するために、$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
...

シミュレータでプロジェクトをテストする

Actions Console には、アクションをプレビューするためのシミュレータが用意されています。シミュレータを使用すると、デバッグ情報の表示、デバイス機能の設定、ロケールのシミュレーションなどを行うことができます。

図 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