Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

REST インタフェース

InterSystems IRIS® Data Platform の %iKnow.REST.v1Opens in a new tab クラスの一般的な NLP タスクに REST API インタフェースが提供されます。この REST API は、基礎 (ドメインと構成のクエリ)、従来型のクエリ (セマンティックを含む)、シンプルなドメイン処理 (ソースの追加/削除、skiplist 管理)、およびマッチング API とディクショナリ API に対するサポートを扱います。

この API の主な属性のいくつかを以下に示します。

  • ほとんどの API 呼び出しには GET と POST のバリアントがあります。基本ではないすべてのパラメータに対する GET バリアントは既定の値となり、最も簡単に呼び出せます。POST バリアントは、Request オブジェクトとして渡された JSON 文字列を使用してすべての関連引数へのアクセスを提供します。これは、URL に入力する内容を補完し、重複している場合にはこの内容を上書きします。例えば、スラッシュを含む一部のエンティティ値は、GET 要求では使用できませんが、POST 要求で送信される JSON プロパティとして指定できます。

  • POST 要求に対して使用可能な引数は %iKnow.REST.v1Opens in a new tab のクラス・リファレンスで、いくつかの共有引数 (フィルタと強調表示) は %iKnow.REST.BaseOpens in a new tab で簡潔に説明されています。

  • URL は全体を必ず小文字で表記します。POST 引数と返された JSON プロパティ名は、キャメルケースで表記します。ただし、最初の文字は小文字になります。

  • 返された JSON は一般的に包括的なものであり、対応するフラット (SQL と互換性のある) クエリで提供されるものよりもはるかに多くの情報を返します。例えば、エンティティを含むすべてのソースを要求すると、ソース、メタデータ、および必要に応じて強調表示されたスニペットのリストが返されます。パフォーマンス上の理由で、この機能のいくつかを除外することができますが、既定では、ほとんどの機能が自動的に含まれます。

Swagger

NLP REST API のドキュメントは、OpenAPI SpecificationOpens in a new tab (SwaggerOpens in a new tab とも呼ばれます) を使用して完全に作成されます。YAML の記述には "/swagger" エンドポイントからアクセスでき、この API の最上部で便利な GUI 機能を提供する swagger-uiOpens in a new tab へ直接ロードできます。

それを使用するには、swagger-ui をインストールするか、http://petstore.swagger.io に移動して、このエンドポイントを指します。

  • swagger-ui をダウンロードする

  • swagger-ui ダウンロードを unzip します。

  • Swagger ボックスに以下のどちらかを指定します。

    • 最小のセキュリティの InterSystems IRIS : http://localhost:57775/api/iknow/v1/samples/swagger (57775 を Web サーバのポート番号に、samples を必要なネームスペースに置き換えます)。

    • 通常のセキュリティの InterSystems IRIS : http://localhost:57775/api/iknow/v1/samples/swagger?IRISUsername=myname&IRISPassword=mypassword (57775 を Web サーバのポート番号に、myname を InterSystems IRIS ユーザ名に、samples を必要なネームスペースに、mypassword を InterSystems IRIS アカウントのパスワードに置き換えます)。

  • [エクスプローラ] ボタンを選択します。

Swagger を使用して NLP データを返す

各 REST 文の Swagger–UI 表示を使用して、REST API を直接呼び出すか、ブラウザ・ウィンドウで REST API を呼び出すために使用できる要求 URL 値を提供できます (GET 要求用)。

REST API を直接呼び出すには、必須パラメータを指定します。一般的に、NLP REST API には、整数として指定されるドメイン ID パラメータが必要です。例えば、2 という ID を持つドメインのドメインの詳細を GET すると、以下の要求 URL が生成されます。

http://localhost:57775/api/iknow/v1/user/domain/2/details

Swagger インタフェースは、/swagger エンドポイントにアクセスするために使用した URL から使用するネームスペースを推測することに注意してください。例えば、ネームスペース SAMPLES で REST API を呼び出すには、以下の URL を使用して swagger エンドポイントをロードします。

http://localhost:57775/api/iknow/v1/samples/swagger

NLP データが JSON 形式でブラウザに返されます。例えば、この要求 URL は "crashes" という名前のドメインに対して以下の JSON 文字列を返します。

{"id":"2","name":"crashes","parameters":{"DefaultConfig":"crashes.Configuration","DefinitionClass":"User.crashes","ManagedBy":"User.crashes"},"metadata":[{"id":1,"name":"DateIndexed","operators":["=","!=","<","<=",">",">="],"dataType":"date","storage":"normal","caseSensitive":0,"hidden":0}]}

REST 操作

NLP REST 操作は以下のトピックに分類されます。

コア REST API は (ほぼすべての URL の開始時にドメイン ID を指定することで) あらゆる定義済みドメインへのアクセスをサポートしますが、ドメイン固有の REST API を生成して、webapp を通じて単一ドメインを公開することもできます。そのためには、%iKnow.REST.BaseOpens in a new tab クラスにある CreateDomainAPI()Opens in a new tab メソッドを使用して、新しい Web アプリケーションを作成し、新しく作成したクラスを「ディスパッチ・クラス」と呼びます。これは、特定のドメインへのアクセスのみを有効にし、一般的な /api/iknow/ Web アプリケーションを無効にするときに役に立ちます。

これらの REST 操作について、指定のドメインが存在しない場合、特に断りがない限り、その操作では {"errors":[{"error":"ERROR #8021: Domain with id 7 does not exist","code":8021,"domain":"%ObjectErrors","id":"IKNoDomainWithId","params":["7"]}],"summary":"ERROR #8021: Domain with id 7 does not exist"} が返されます。

ドメインと構成

ドメインと構成に対する NLP REST 操作 (“miscellaneous” のカテゴリに分類) は以下のようになります。

  • [ドメインのリスト] :現在のネームスペースですべてのドメインに関する情報を取得するための GET と POST。GetDomains()Opens in a new tab を参照してください。

    定義済みドメインがない場合、{"domains":[]} を返します。それ以外の場合は、ドメイン名の順でドメインの JSON 配列を返します。各ドメインについて、ドメイン ID、ドメイン名、NLP バージョン、definitionClass 名、および sourceCount がリストされます。

    ドメインのリストは、このガイドの “NLP 環境” の章に詳しく説明されています。

  • [リストの構成] :現在のネームスペースですべての構成に関する情報を取得するための GET と POST。GetConfigurations()Opens in a new tab を参照してください。

    NLP に対応したネームスペースには構成 {"configurations":[{"id":1,"name":"DEFAULT","languages":["en"]}]} が割り当てられます。追加の構成を明示的に定義することができます。ドメイン・アーキテクトを使用してドメインを作成すると、NLP は対応する構成を作成します。

    このオプションは、構成名の順で構成の JSON 配列を返します。各構成について、構成 ID、構成名、サポートされている言語の JSON 配列、および (オプションで) userDictionary JSON オブジェクトがリストされます。言語は既定で英語 (["en"]) に設定されます。

    構成のリストは、このガイドの “NLP 環境” の章に詳しく説明されています。

  • [ドメインの詳細] :指定のドメインに関する詳細情報を取得するための GET と POST。GetDomainDetails()Opens in a new tab を参照してください。

    返されるデータには、ドメインの ID、名前、パラメータ、およびメタデータが含まれます。

    • パラメータには、DefaultConfig (domainname.Configuration)、DefinitionClass、および ManagedBy (既定は DefinitionClass) が含まれます。

    • メタデータには、メタデータ ID、メタデータ名 (既定は DateIndexed)、サポートされている演算子の配列、データ型 (DateIndexed はデータ型日付)、ストレージ (既定は通常)、caseSensitive (ブーリアン値)、および非表示 (ブーリアン値) が含まれます。

ソース

ソースに対する NLP REST 操作は以下のようになります。

  • [フィルタ処理されたソース]:指定されたフィルタを渡すすべてのソースを取得するための GET と POST。既定では、すべてのソースを返します。GetSources()Opens in a new tab を参照してください。

    ドメインは存在するものの、フィルタを渡すソースが含まれていない場合は、{"sources":[]} を返します。ソースがある場合は、ID、extId (外部 ID)、メタデータ (ソースのインデックスが作成された日付と時間)、および各ソースのテキスト断片を返します。この断片はテキストからの 2 つの文で構成されます。それらの文が連続するものではない場合、省略記号 (3 つのドット) によって連続していない部分が示されます。テキストに含まれる文が 2 つ以下の場合、この断片にはフルテキストが含まれます。

    ソースのフィルタ処理は、このガイドの“ソースのフィルタ処理” の章に詳しく説明されています。

  • [エンティティ別のソース]:指定のエンティティを含むソースを取得するための GET と POST。 GetSourcesByEntity()Opens in a new tab を参照してください。

    ドメインは存在するものの、フィルタを渡すソースが含まれていない場合は、{"sources":[]} を返します。ソースがある場合は、ID、extId (外部 ID)、メタデータ (ソースのインデックスが作成された日付と時間)、および各ソースのテキスト断片を返します。この断片は、指定のエンティティが含まれるテキストからの (多くても) 2 つの文で構成されます。これらの文は必ずしも順番どおりに表示されるとは限りません。

    エンティティの一致によるソースのフィルタ処理は、このガイドの“ソースのフィルタ処理” の章に詳しく説明されています。

  • [CRC 別のソース]:指定された CRC を含むソースを取得するための GET と POST。これらの操作を使用して、CRC (concept:relation:concept)、CR (concept:relation)、RC (:relation:concept)、または CC (concept::concept) を取得することができます。GetSourcesByCRC()Opens in a new tab を参照してください。

    ドメインは存在するものの、CRC を含むソースが含まれていない場合は、{"sources":[]} を返します。CRC を含むソースがある場合は、ID、extId (外部 ID)、メタデータ (ソースのインデックスが作成された日付と時間)、および各ソースのテキスト断片を返します。この断片は、指定された CRC が含まれるテキストからの (多くても) 2 つの文で構成されます。これらの文は必ずしも順番どおりに表示されるとは限りません。

    CR の後には概念が必ず続きます。そのため、CR pilot:stated は "pilot stated the airplane"、"pilot stated he"、および “pilot stated \"I then" を返します。"pilot stated that" や "pilot stated to" は返しません。

  • [類似ソース]:指定されたソースに類似するソースを取得するための GET と POST。GetSimilarSources()Opens in a new tab を参照してください。

    ドメインは存在するものの、類似ソースが含まれていない場合は、{"sources":[]} を返します。類似ソースがある場合、類似性スコアによる降順でエンティティの JSON 配列を返します。同じ類似性スコアを持つ相似した複数のエンティティがある場合は、ID 順でリストされます。各類似ソースについて、ID、extId (外部 ID)、スコア (類似性スコア)、percentageMatched、percentageNew、numberOfEntitiesInRefSource、numberOfEntitiesInCommon、numberOfEntitiesInThisSource、metadata (ソースのインデックスが作成された日付と時間)、および各ソースのテキスト断片を返します。この断片は、類似エンティティが含まれるテキストからの (多くても) 2 つの文で構成されます。

    類似ソースは、このガイドの “NLP クエリ” の章に詳しく説明されています。

  • [ソースの詳細]:指定されたソースに関する詳細を取得するための GET と POST。GetSourceDetails()Opens in a new tab を参照してください。

    指定されたソースについて、仮想ブーリアン、メタデータ (ソースのインデックスが作成された日付と時間)、およびソースのフルテキストを返します。

  • [ソースの追加]:ドメインにソースを追加するための POST。AddSource()Opens in a new tab を参照してください。

    ソースの追加は、このガイドの “プログラムによるテキスト・データのロード” の章に詳しく説明されています。

  • [ソースの削除]:ドメインからソースを削除するための DELETE。DropSource()Opens in a new tab を参照してください。

    ソースの削除は、このガイドの “プログラムによるテキスト・データのロード” の章に詳しく説明されています。

  • [ソースのメタデータ]:特定のソースのメタデータを更新するための POST。SetMetadata()Opens in a new tab を参照してください。

エンティティ

エンティティに対する NLP REST 操作は以下のようになります。

  • [上位エンティティ]:指定のドメインで上位エンティティを取得するための GET と POST。GetEntities()Opens in a new tab を参照してください。

    エンティティを含む定義済みドメインがない場合、{"entities":[]} を返します。エンティティがある場合、周期による降順でエンティティの JSON 配列を返します。同じ周期を持つ複数のエンティティがある場合は、ID 順でリストされます。各エンティティは、ID、値、周期、およびスプレッドのキー/値ペアを持つ JSON オブジェクトとしてリストされます。

    上位エンティティは、このガイドの “NLP クエリ” の章に詳しく説明されています。

  • [類似エンティティ]:指定した文字列に類似するエンティティを取得するための GET と POST。GetSimilarEntities()Opens in a new tab を参照してください。

    類似エンティティがない場合、{"entities":[]} を返します。類似エンティティがある場合、周期による降順でエンティティの JSON 配列を返します。同じ周期を持つ相似した複数のエンティティがある場合は、ID 順でリストされます。各エンティティは、ID、値、周期、およびスプレッドのキー/値ペアを持つ JSON オブジェクトとしてリストされます。

    類似エンティティは、このガイドの “NLP クエリ” の章に詳しく説明されています。

  • [関連するエンティティ]:指定エンティティに関連するエンティティを取得するための GET と POST。GetRelatedEntities()Opens in a new tab を参照してください。

    関連するエンティティがない場合、{"entities":[]} を返します。関連するエンティティがある場合、近似による降順でエンティティの JSON 配列を返します。同じ近似を持つ相似した複数のエンティティがある場合は、ID 順でリストされます。各エンティティは、ID、値、および近似のキー/値ペアを持つ JSON オブジェクトとしてリストされます。

    関連するエンティティは、このガイドの “NLP クエリ” の章に詳しく説明されています。

  • [エンティティの詳細]:指定されたエンティティに関する詳細を取得するための GET と POST。GetEntityDetails()Opens in a new tab を参照してください。

    指定のエンティティがドメインに存在しない場合、または指定のドメインが存在しない場合、{"id":"","value":"aardvark"} を返します。エンティティが見つかった場合は、ID、値のキー/値ペアを持つ JSON オブジェクト、および metricsAsConcept、metricsAsRelation、metricsAsAn の各サブ配列を返します。各サブ配列では、周期、スプレッド、および tfidf がリストされます。

    エンティティが概念としてのみ発生する場合、metricsAsRelation の値は 0 になり、metricsAsAny の値は metricsAsConcept の値と同じになります。エンティティが関係としてのみ発生する場合、metricsAsRelation の値は 0 になり、metricsAsAny の値は metricsAsRelation の値と同じになります。エンティティが概念としても関係としても発生する場合、周期とスプレッドに対する metricsAsAny の値は、それぞれの概念の値と関係の値の合計になります。tfidf の値は、対応する概念の値と関係の値から算出されます。

文に対する NLP REST 操作は以下のようになります。

  • [エンティティ別の文]:指定のエンティティを含む文を取得するための GET と POST。GetSentencesByEntity()Opens in a new tab を参照してください。

    指定のエンティティを含む文がない場合、{"sentences":[]} を返します。エンティティを含む文がある場合、文の JSON 配列を返します。各文について、文 ID、ソース ID、文のテキスト、および文の部分をリストします。部分は文の順にリストされます。各部分は部分配列の要素です。部分配列の各部分について、partld、リテラル (大文字/小文字の区別は元のまま)、ロール (概念、関係、pathRelevant、または nonRelevant)、entityId、およびエンティティ (小文字) をリストします。部分が nonRelevant の場合、entityId やエンティティはリストされません。

  • [文の詳細]:指定された文に関する詳細を取得するための GET と POST。GetSentenceDetails()Opens in a new tab を参照してください。

    指定された文が存在する場合、文 ID、文の部分、テキスト、および sourceId を返します。部分は文の順にリストされます。各部分は部分配列の要素です。部分配列の各部分について、partld、リテラル (大文字/小文字の区別は元のまま)、ロール (概念、関係、pathRelevant、または nonRelevant)、entityId、およびエンティティ (小文字) をリストします。部分が nonRelevant の場合、entityId やエンティティはリストされません。

パスと CRC

パスと CRC (概念 - 関係 - 概念の文字列) に対する NLP REST 操作は以下のようになります。

  • [上位 のCRC]:指定のドメインで上位の CRC を取得するための GET と POST。GetCRCs()Opens in a new tab を参照してください。

    CRC を含むソースがない場合、{"crcs":[]} を返します。周期による降順で CRC の JSON 配列を返します。同じ周期を持つ複数の CRC がある場合は、ID 順でリストされます。各 CRC について、id、ヘッド概念、関係、テール概念、周期、およびスプレッドをリストします。一部の CRC では、ヘッドまたはテールの値は "" (空の文字列) になります。例えば、ヘッドのキーと値のペアは、CRC で関係 “according to” または “during” で始まる値 "" を持ちます。この CRC のヘッドは指定されていないためです。テールのキーと値のペアは、CRC で “occurred” または “said” のような関係を含む値 "" を持ちます。この CRC のテールは指定されていないためです。

  • [エンティティ別の CRC]:指定のエンティティを含む CRC を取得するための GET と POST。GetCRCsByEntity()Opens in a new tab を参照してください。

    指定のエンティティを含む CRC を持つソースがない場合、{"crcs":[]} を返します。その他の場合は、周期による降順で CRC の JSON 配列を返します。同じ周期を持つ複数の CRC がある場合は、ID 順でリストされます。各 CRC について、id、ヘッド概念、関係、テール概念、周期、およびスプレッドをリストします。一部の CRC では、ヘッドまたはテールの key:value ペアは省略されます。

  • [エンティティ別のパス]:指定のエンティティを含むパスを取得するための GET と POST。GetPathsByEntity()Opens in a new tab を参照してください。

    指定のエンティティを含むパスを持つソースがない場合、{"paths":[]} を返します。その他の場合は、パスの JSON 配列を返します。各パスは、パス ID、エンティティ配列、sourceId、および sentenceId で構成されます。エンティティ配列には、各エンティティのエンティティ ID、partId、エンティティ値、ロール指定子 (概念、関係、または pathRelevant)、および (オプションで) 属性配列が含まれます。属性配列は、タイプ (否定演算子)、レベル (パス、語)、またレベルが語の場合は key:value ペアの語で構成されます。例えば、"attributes":[{"type":"negation","level":"path"}]}

ディクショナリとマッチング

ディクショナリに対する NLP REST 操作は以下のようになります。

ディクショナリを使用したマッチング処理のための NLP REST 操作は以下のようになります。

  • [ソース (複数) のマッチング]:ディクショナリに対してすべてのソースをマッチングさせるための GET と POST。MatchAll()Opens in a new tab を参照してください。

    ディクショナリの一致によるソースのフィルタ処理は、このガイドの“ソースのフィルタ処理” の章に詳しく説明されています。

  • [ソースのマッチング]:ディクショナリに対して指定のソースをマッチングさせるための GET と POST。GetMatchesBySource()Opens in a new tab を参照してください。

  • [ディクショナリの一致]:指定されたソースについてディクショナリの一致をすべて取得するための GET と POST。複数のディクショナリを指定できます。MatchSource()Opens in a new tab を参照してください。

  • [項目の一致]:指定されたディクショナリ項目に対するすべての一致を取得するための GET と POST。GetMatchesByItem()Opens in a new tab を参照してください。

Skiplist

skiplist に対する NLP REST 操作は以下のようになります。

  • [skiplist の一覧]:ドメインの全 skiplist の一覧を取得するための GET と POST。"GetSkiplists()Opens in a new tab" を参照してください。

    定義済み skiplist がない場合、{"skiplists":[]} を返します。1 つ以上の skiplist がある場合、skiplist の JSON 配列を返します。各 skiplist は、ID、名前に対するキー/値ペアを持つ JSON オブジェクトと、要素の JSON 配列としてリストされます。

  • [skiplist の作成]:skiplist を新規作成するための GET と POST。"CreateSkiplist()Opens in a new tab" を参照してください。

    skiplist の作成については、このガイドの “Skiplist” の章に詳しく説明されています。

  • [skiplist の取得]:指定された skiplist の内容を取得するための GET と POST。"GetSkiplistDetails()Opens in a new tab" を参照してください。

    ID、名前に対するキー/値のペアを持つ JSON オブジェクトと、要素の JSON 配列として、skiplist ID で指定される skiplist を取得します。

  • [skiplist の削除]:指定された skiplist を削除するための DELETE。"DropSkiplist()Opens in a new tab" を参照してください。

  • [skiplist のクリア]:指定された skiplist の内容をすべてクリア (削除) するための GET と POST。"ClearSkiplist()Opens in a new tab" を参照してください。

  • [エンティティの追加]:指定された skiplist にエンティティを追加するための GET と POST。"AddStringToSkiplist()Opens in a new tab" を参照してください。

  • [エンティティの削除]:指定された skiplist からエンティティを削除するための GET と POST。"RemoveStringFromSkiplist()Opens in a new tab" を参照してください。

FeedbackOpens in a new tab