Dialogflow の Entities を REST API でメンテナンス

最近、Google Assistant アプリ構築IDEとして、Actions Builder が登場し、Dialogflow を使用する機会も減ってくるのかなと感じる今日この頃（遅め）。しかし、Google Assistant 以外のアプリで自然言語処理を行う際に利用しないとも限らないので、Dialogflow に関する内容を忘れないようにリンクメモ程度として残しておこうと思います。

Dialogflow の Entities のメンテナンスは、そのコンソール画面から行うことができるのですが、メンテナンスしてもらいたい人にそのままの Dialogflow のコンソール画面を共有するとしてほしくない箇所を変更される可能性があるという心配がありました。
そこで Entities のメンテナンスだけできるといったような、独自画面を作れないかなと思い、REST API を調べたのでまとめてみました。（調査不十分の箇所があります。あらかじめご了承ください）

Dialogflow のバージョンについて

今回の記事で使用する Dialogflow のバージョンは "V2" になります。
V1、V2beta とは REST API の内容が大きく変わるのでご注意ください。Migration Guide で比較などできます。また V1 は 2020年5月31日でサポートが切れているようなので、バージョン対応をしておきましょう。

EntityType の作成

まず初めに、、エンティティには、"エンティティタイプ"と"エンティティエントリ"があります。
エンティティタイプとエンティティエントリは、API においては EntityType と EntityType.Entity とそれぞれ記載され、上位下位の関係、容器と中身という関係になります。
当記事では今後、EntityType は、"EntityType"、EntityType.Entity は、"Entity"と記載していきます。

エンティティを作成していく時は、EntityType を作成した後に、EntityType.Entity を作成することになります。（EntityType 作成時、その中身である EntityType.Entity を同時作成することができます。）

EntityType を作成するには、下記 REST API を利用します。
Method: projects.agent.entityTypes.create

エンドポイントは下記のようになっており、、

POST https://dialogflow.googleapis.com/v2/{parent=projects/*/agent}/entityTypes

{}部の入力例は "projects/testproject/agent" といった感じになります。

なお当 API では、displayName の内容が既存のものと同じだと新規作成が行われません。

EntityType が作成されると、EntityType に "Entity Type ID" が振られます。
"Entity Type ID" は、EntityType の変更や、Entity の作成、編集の際に利用されます。

コンソールでいうと上図赤枠の部分が "Entity Type ID" となります。

EntityType の編集

EntityType を編集する際には、PATCH メソッドの REST API を利用します。
Method: projects.agent.entityTypes.patch

エンドポイントは下記のようになっています。{}部の入力例は "projects/testproject/agent" のようになります。

PATCH https://dialogflow.googleapis.com/v2/{parent=projects/*/agent}/entityTypes

当 API で EntityType を編集するとその中身の Entity 内容も上書きされてしまうので注意が必要です。

Entity の作成

Entity を新たに作成するには、EntityType の下階層の REST API を利用します。
Method: projects.agent.entityTypes.entities.batchCreate

POST https://dialogflow.googleapis.com/v2/{parent=projects/*/agent/entityTypes/*}/entities:batchCreate

エンドポイントは上記のようになり、"entityTypes" 後の変数に入るのは、EntityType の ID になります。対象の ID は、Method: projects.agent.entityTypes.list で一括して取得することもできますが、コンソールで開くと上図で示したように URL に ID が出ているのでそこから取得するのが手っ取り早かったりします。

当 API では、"value"が同じ値の場合、上書きでなく、挿入が行われます。

Entity の編集

Entity の編集に関して、詳しく仕様が理解できていません。（ご存知の方教えて下さい！！）

REST API の内容的に、EntityType の下階層にある Method: projects.agent.entityTypes.entities.batchUpdate を使用し、Request Body 項目である "updateMask" パラメータを適切に設定すれば編集が可能なようですが、"updateMask" の仕様がよくわからないので困ってます。。

まとめ

Entity は調整することが多い箇所です。開発者自ら調整してもいいのですが、できれば運用者が Entity 登録を行った方が色々試せていいかと思います。
今回、編集の API の仕様がよくわからないといった具合でしたが、上記記載した以外の API も色々組み合わせればなんとかならないこともないので、うまいこと API を利用していきたいと思います。
開発者、運用者で力を合わせて、アシスタントアプリを成長させていけると良いですね。

いつのまにか Dialogflow CX とかいうものも出ていますし、今後も色々触っていけたらと思います。（まずは Actions Builder から…）