Microsoft 365 Copilotの API プラグイン マニフェスト スキーマ
重要
API プラグインは、 宣言型エージェント内のアクションとしてのみサポートされます。 Microsoft 365 Copilotでは有効になっていません。
API プラグインを使用すると、Microsoft 365 Copilotは OpenAPI の説明で説明されている REST API と対話できます。 API プラグインの OpenAPI の説明では、Copilot が操作できる REST API について説明します。 さらに、API プラグインには、プラグインの名前、説明、バージョンなど、プラグインに関するメタデータを提供するプラグイン マニフェスト ファイルが含まれています。 プラグイン マニフェストには、サポートされている API や実行できる操作など、プラグインの機能に関する情報も含まれています。
次の記事では、API プラグイン マニフェスト ファイルで使用されるスキーマについて説明します。 API プラグインの詳細については、「Microsoft 365 Copilot用 API プラグイン」を参照してください。
JSON スキーマ
このドキュメントで説明されているスキーマは、 JSON スキーマ 形式 でこちらで確認できます。
規則
URL 内の相対参照
特に指定しない限り、URL であるプロパティはすべて相対参照になる場合があります。 マニフェスト ドキュメント内の相対参照は、マニフェスト ドキュメントの場所を基準とします。
文字列の長さ
特に指定しない限り、すべての文字列プロパティを 4K 文字に制限する必要があります。 この文字列の長さは、ドキュメント全体に許容されるサイズを与えるわけではありません。 実装では、マニフェストの長さに独自の実用的な制限を自由に適用できます。
認識されないプロパティ
このドキュメントで定義されている JSON オブジェクトでは、説明されているプロパティのみがサポートされています。 JSON オブジェクトの認識されないプロパティは、ドキュメント全体を無効にする必要があります。
文字列のローカライズ
ローカライズ可能な文字列では、リテラル値の代わりにローカライズ キーを使用できます。 構文は [[key_name]]
で、 key_name
はローカライズ ファイルの localizationKeys
プロパティのキー名です。 ローカライズの詳細については、「 エージェントのローカライズ」を参照してください。
ローカライズされた文字列の例
{
"schema_version": "v2.1",
"name_for_human": "[[plugin_name]]",
"description_for_human": "[[plugin_description]]"
}
プラグイン マニフェスト オブジェクト
プラグイン マニフェスト ドキュメントのルートは、プラグインを記述するプロパティを含む JSON オブジェクトです。
プラグイン マニフェスト オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
schema_version |
String | 必須。 スキーマのバージョン。 以前のバージョンは v1 と v2 。
v2.1 に設定する必要があります。 |
name_for_human |
String | 必須です。 プラグインの人間が判読できる短い名前。 空白以外の文字が少なくとも 1 つ含まれている必要があります。 20 文字を超える文字は無視できます。 このプロパティはローカライズ可能です。 |
namespace |
String | 非推奨。 省略可能。 |
description_for_model |
String | 省略可能。 モデルに提供されるプラグインの説明。 この説明では、プラグインの目的と、その機能が関連する状況について説明する必要があります。 2048 を超える文字は無視できます。 このプロパティはローカライズ可能です。 |
description_for_human |
String | 必須です。 プラグインの人間が判読できる説明。 100 文字を超える文字は無視できます。 このプロパティはローカライズ可能です。 |
logo_url |
String | 省略可能。 オーケストレーターによって使用される可能性があるロゴをフェッチするために使用される URL。 実装では、視覚的な要件を満たすロゴを提供する別の方法が提供される場合があります。 このプロパティはローカライズ可能です。 |
contact_email |
String | 省略可能。 安全性/モデレーション、サポート、非アクティブ化のための連絡先の電子メール アドレス。 |
legal_info_url |
String | 省略可能。 プラグインのサービス条件を含むドキュメントを検索する絶対 URL。 このプロパティはローカライズ可能です。 |
privacy_policy_url |
String | 省略可能。 プラグインのプライバシー ポリシーを含むドキュメントを検索する絶対 URL。 このプロパティはローカライズ可能です。 |
functions |
Function オブジェクトの配列 | 省略可能。 プラグインで使用できる関数を記述する関数オブジェクトのセット。 各関数オブジェクト名は、配列内で一意である必要があります。 配列の順序は重要ではありません。
functions プロパティが存在せず、OpenAPI ランタイムがある場合、関数は OpenAPI 操作から推論されます。 |
runtimes |
OpenAPI ランタイム オブジェクトの配列 | 省略可能。 プラグインによって使用されるランタイムを記述するランタイム オブジェクトのセット。 |
capabilities |
Plugin capabilities オブジェクト | 省略可能。 プラグインの機能について説明します。 |
関数オブジェクト
モデルが関数と対話する方法に関連する情報。
関数オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
id |
String | 省略可能。 |
name |
String | 必須です。 この関数を一意に識別する文字列。 ランタイム オブジェクトは、この識別子を参照して、ランタイムを関数にバインドする場合があります。 関数が OpenAPI ランタイムにバインドされている場合、値は OpenAPI 説明の operationId 値と一致する必要があります。 値は、 ^[A-Za-z0-9_]+$ 正規表現と一致する必要があります。 |
description |
String | 省略可能。 トークン コンテキストの長さの考慮事項や、プラグインのプロンプトを改善するための使用キーワード (keyword)など、モデルに合わせて調整された説明。 |
parameters |
関数パラメーター オブジェクト | 省略可能。 ランタイムに依存しない方法で関数のパラメーターを記述するプロパティを含むオブジェクト。
これは json スキーマの形状を反映しますが、JSON スキーマ機能の小さなサブセットのみをサポートします。
parameters プロパティが存在しない場合、型のランタイム オブジェクトによって記述された関数OpenApi OpenAPI の説明を使用してパラメーターを決定します。 JSON オブジェクトの各メンバーは、パラメーターのセマンティクスを記述する関数パラメーター オブジェクトです。 |
returns |
Return オブジェクト OR リッチ リターン オブジェクト | 省略可能。 関数から返される値のセマンティクスについて説明します。 |
states |
関数状態オブジェクト | 省略可能。 オーケストレーターの状態の状態オブジェクトを定義します。 |
capabilities |
関数機能オブジェクト | 省略可能。 関数の呼び出し中にオーケストレーターのオプション機能を構成するために使用されるデータのコレクションが含まれます。 |
関数オブジェクトの例
{
"functions": [
{
"name": "add_todo",
"description": "Adds a new Todo",
"parameters": {
"type": "object",
"properties": {
"description": {
"type": "string"
}
},
"required": [
"description"
]
},
"returns": {
"type": "string"
}
}
]
}
関数パラメーター オブジェクト
関数に渡すことができるパラメーターのセットを識別するために使用されるオブジェクト。 このオブジェクトは、JSON スキーマ オブジェクトの形状をミラーするように構成されていますが、JSON スキーマ キーワードのサブセットのみをサポートします。
関数パラメーター オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 省略可能。 JSON スキーマ型。
object に設定する必要があります。 |
properties |
関数パラメーターのプロパティ オブジェクト | 必須です。 パラメーター名を定義にマップするオブジェクト。 |
required |
文字列の配列 | 省略可能。 必要なパラメーターであるプロパティの名前。 JSON スキーマとは異なり、この配列の値は、 properties プロパティに記載されている名前と一致する必要があります。 |
関数パラメーター オブジェクトの例
{
"type": "object",
"properties": {
"param1": {
"type": "string"
},
"param2": {
"type": "number"
}
},
"required": [
"param1"
]
}
関数パラメーターのプロパティ オブジェクト
パラメーター名を定義にマップするオブジェクト。
関数パラメーターのプロパティ オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
名前の一致 ^[A-Za-z0-9_]+$ |
関数パラメーター オブジェクト | 省略可能。 プロパティ名と一致するパラメーターに対応するパラメーター定義。 |
関数パラメーター オブジェクト
関数パラメーターのセマンティクスを表す オブジェクト。
関数パラメーター オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 必須です。 パラメーターの型を指定します。 可能な値は、string 、array 、boolean 、integer 、number です。 |
items |
関数パラメーター オブジェクト | 省略可能。 配列内の 1 つの要素を記述する関数パラメーター オブジェクト。
type がarray されている場合にのみ存在する必要があります。 |
enum |
文字列の配列 | 省略可能。 このパラメーターの有効な値の配列。
type がstring されている場合にのみ存在する必要があります。 |
description |
String | 省略可能。 パラメーターの説明です。 |
default |
配列、ブール値、文字列、数値、整数 | 省略可能。 省略可能なパラメーターの値が指定されていない場合に API が使用する値を示す、 type プロパティで指定された型の値。 |
関数パラメーターの例
{
"type": "string",
"description": "The color of the item",
"enum": [
"green",
"blue",
"orange"
]
}
Return オブジェクト
関数から返される値のセマンティクスを格納します。
戻り値オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 必須です。 API によって返される値の型を指定します。 使用可能な値は、 string です。 |
description |
String | 省略可能。 API によって返される値の説明。 |
リッチ リターン オブジェクト
関数から、リッチ応答プロトコルと互換性のある応答が返されることを示します。
リッチ リターン オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
$ref |
String | 必須。
https://copilot.microsoft.com/schemas/rich-response-v1.0.json に設定する必要があります。 |
関数状態オブジェクト
オーケストレーターの状態の状態オブジェクトを定義します。
関数 states オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
reasoning |
State オブジェクト | 省略可能。 モデルが関数を呼び出して計算を実行できる状態。 |
responding |
State オブジェクト | 省略可能。 モデルがユーザーに表示されるテキストを生成できる状態。 モデルは応答状態の関数を呼び出すことはできません。 |
disengaging |
State オブジェクト | 省略可能。 |
State オブジェクト
特定のオーケストレーター状態で関数が呼び出されたときの特定の命令が含まれます。
state オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
description |
String | 省略可能。 特定のオーケストレーター状態で使用する場合の関数の目的について説明します。 |
instructions |
配列、文字列 | 省略可能。 特定のオーケストレーター状態でこの関数を使用する方法に関する命令をオーケストレーターに提供するために使用される文字列または文字列の配列。 1 つの文字列を指定すると、組み込みの関数プロンプトをオーバーライドする命令の完全なセットを提供する意図が示されます。 文字列の配列を指定すると、組み込みの関数プロンプト メカニズムを拡張する意図が示されます。 |
examples |
配列、文字列 | 省略可能。 この関数を呼び出す方法の例をオーケストレーターに提供するために使用される文字列または文字列の配列。 |
State オブジェクトの例
{
"functions": [
{
"name": "searchEmails",
"description": "search for Emails from using 3S search Service",
"states": {
"reasoning": {
"description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
"instructions": [
"Examine the output of `searchEmails(**params) -> str`.",
"Do not include any information that is not present in the JSON results.",
"Exclude any irrelevant data from the JSON results",
"Determine if the response contains an error field.",
"If an error is present, provide the error code and error message extracted from the response JSON.",
"If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
],
"examples": []
}
}
}
]
}
関数機能オブジェクト
関数の呼び出し中にオーケストレーターのオプション機能を構成するために使用されるデータのコレクションが含まれます。
関数の機能オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
confirmation |
確認オブジェクト | 省略可能。 関数を呼び出す前にユーザーに表示する必要がある確認ダイアログについて説明します。 |
response_semantics |
応答セマンティクス オブジェクト | 省略可能。 オーケストレーターが応答ペイロードを解釈し、視覚的なレンダリングを提供する方法について説明します。 |
確認オブジェクト
オーケストレーターが、関数を呼び出す前にユーザーに確認を求める方法について説明します。
確認オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 省略可能。 確認の種類を指定します。 可能な値は、None 、AdaptiveCard です。 |
title |
String | 省略可能。 確認ダイアログのタイトル。 このプロパティはローカライズ可能です。 |
body |
String | 省略可能。 確認ダイアログのテキスト。 このプロパティはローカライズ可能です。 |
応答セマンティクス オブジェクト
応答ペイロードのセマンティクスを識別し、 アダプティブ カードを使用した豊富なビジュアル エクスペリエンスでその情報のレンダリングを可能にする情報が含まれています。
応答セマンティクス オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
data_path |
String | 必須です。 JSONPath RFC9535 クエリ。各アイテムで指定されたテンプレートを使用してレンダリングされる関数応答から要素のセットを識別します。 |
properties |
応答セマンティクスのプロパティ オブジェクト | 省略可能。 既知のデータ要素への JSONPath クエリのマッピングを許可します。 各 JSONPath クエリは、結果の値に対して相対的です。 |
static_template |
Object | 省略可能。
アダプティブ カード スキーマとテンプレート言語に準拠する JSON オブジェクト。 このアダプティブ カード インスタンスは、プラグイン応答の結果をレンダリングするために使用されます。 この値は、template_selector が存在しないか、アダプティブ カードへの解決に失敗した場合に使用されます。 |
oauth_card_path |
String | 省略可能。 |
静的テンプレートの例
{
"functions": {
"capabilities": {
"response_semantics": {
"data_path": "$.resources",
"properties": {
"title": "$.name",
"subtitle": "$.location",
"url": "$.href",
"information_protection_label": "$.ipLabel"
},
"static_template": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "${name}",
"weight": "Bolder"
},
{
"type": "TextBlock",
"text": "${description}"
}
],
"action": [
{
"type": "Action.OpenUrl",
"title": "View",
"text": "${href}"
}
]
}
}
}
}
}
動的テンプレートの例
{
"functions": {
"capabilities": {
"response_semantics": {
"data_path": "$.attachments",
"properties": {
"title": "$.title",
"subtitle": "$.subtitle",
"url": "$.url",
"thumbnail_url": "$.thumbnailUrl",
"template_selector": "$.template"
}
}
}
}
}
応答セマンティクスのプロパティ オブジェクト
既知のデータ要素への JSONPath クエリのマッピングを許可します。 各 JSONPath クエリは、結果の値に対して相対的です。
応答セマンティクスのプロパティ オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
title |
String | 省略可能。 結果の引用文献のタイトル。 |
subtitle |
String | 省略可能。 結果の引用文献の字幕。 |
url |
String | 省略可能。 結果の引用文献の URL。 |
thumbnail_url |
String | 省略可能。 結果のサムネイル画像の URL。 |
information_protection_label |
String | 省略可能。 結果の内容のデータ秘密度インジケーター。 |
template_selector |
String | 省略可能。 結果のレンダリングに使用するアダプティブ カード インスタンスへの JSONPath 式。 |
OpenAPI ランタイム オブジェクト
プラグインが OpenAPI 関数を呼び出す方法について説明します。
OpenAPI ランタイム オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 必須です。 このランタイムを OpenAPI ランタイムとして識別します。
OpenApi に設定する必要があります。 |
auth |
ランタイム認証オブジェクト | 必須です。 ランタイムを呼び出すために必要な認証情報。 |
run_for_functions |
文字列の配列 | 省略可能。 このランタイムで使用できる関数の名前。 このプロパティを省略すると、ランタイムによって記述されたすべての関数を使用できます。 指定された文字列値にはワイルドカードを含めることができます。 複数のランタイムで、同じ関数のサポートを暗黙的または明示的に宣言することはできません。 |
spec |
OpenAPI 仕様オブジェクト | 必須です。 ランタイムを呼び出すために必要な OpenAPI 情報が含まれています。 |
OpenAPI 仕様オブジェクト
ランタイムを呼び出すために必要な OpenAPI 情報が含まれています。
OpenAPI 仕様オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
url |
String | 省略可能。 GET 要求で呼び出される OpenAPI 仕様をフェッチする URL。 このメンバーは、 api_description が存在しない限り必要です。 |
api_description |
String | 省略可能。 OpenAPI の説明を含む文字列。 このメンバーが存在する場合、 url は必須ではなく、存在する場合は無視されます。 |
progress_style |
String | 省略可能。 関数の進行状況を表示するために使用される進行状況スタイル。 使用可能な値: None 、ShowUsage 、ShowUsageWithInput 、ShowUsageWithInputAndOutput 。 |
OpenAPI 仕様オブジェクトの例
{
"runtimes":
[
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "https://example.org/api/openapi.yaml",
}
}
]
}
ランタイム認証オブジェクト
ランタイムに対する認証にプラグインによって使用される情報が含まれます。
ランタイム認証オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
type |
String | 省略可能。 関数を呼び出すために必要な認証の種類を指定します。 可能な値は None 、OAuthPluginVault 、ApiKeyPluginVault です。 |
reference_id |
String | 省略可能。
type がOAuthPluginVault またはApiKeyPluginVault されるときに使用される値。
reference_id 値は、必要な認証構成値を指定するときに個別に取得されます。 このメカニズムは、プラグイン マニフェストにシークレット値を格納する必要を防ぐために存在します。 |
ランタイム認証オブジェクトの例
{
"type": "OAuthPluginVault",
"reference_id": "0123456-abcdef"
}
Plugin capabilities オブジェクト
プラグインの機能について説明します。
プラグイン機能オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
conversation_starters |
Conversation スターター オブジェクトの配列 | 省略可能。 プラグインを呼び出す方法に関する提案をユーザーに表示できる会話スターター。 |
会話スターター オブジェクト
プラグインが回答できる質問の例。
会話スターター オブジェクトには、次のプロパティが含まれています。
プロパティ | 型 | 説明 |
---|---|---|
text |
String | 必須です。 会話スターターのテキスト。 このプロパティはローカライズ可能です。 |
title |
String | 省略可能。 会話スターターのタイトル。 このプロパティはローカライズ可能です。 |
会話スターター オブジェクトの例
{
"conversation_starters": [
{
"title": "Developer tasks",
"text": "What issues are assigned to me?"
}
]
}
マニフェストの例
この記事で説明されているほとんどのマニフェスト プロパティとオブジェクト プロパティを使用するプラグイン マニフェスト ファイルの例を次に示します。
{
"schema_version": "v2",
"name_for_human": "{{ 'nameForHuman' | localize: 'en-us' }}",
"description_for_human": "{{ 'descriptionForHuman' | localize: 'en-us' }}",
"description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
"capabilities": {
"localization": {
"en-us": {
"nameForHuman": {
"message": "Contoso Real Estate",
"description": "Name for human, in English"
},
"descriptionForHuman": {
"message": "Find up-to-date, detailed real estate properties for sale on the market",
"description": "Description for human, in English"
}
},
"fr-fr": {
"nameForHuman": {
"message": "Contoso Immobilier",
"description": "Name for human, in French"
},
"descriptionForHuman": {
"message": "Trouvez des propriétés immobilières à vendre sur le marché",
"description": "Description for human, in French"
}
}
}
},
"functions": [
{
"name": "getListings",
"description": "Get a list of properties matching the specified criteria",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city to search properties in"
},
"bedrooms": {
"type": "number",
"description": "The number of bedrooms the property should have"
},
"bathrooms": {
"type": "number",
"description": "The number of bathrooms the property should have"
},
"amenities": {
"type": "array",
"description": "The list of amenities the property should have",
"items": {
"type": "string",
"description": "One amenity the property should have",
"enum": [
"air conditioning",
"balcony",
"dishwasher",
"elevator",
"fireplace",
"furniture",
"garden",
"gym",
"heating",
"jacuzzi",
"laundry room",
"microwave",
"no furniture",
"parking",
"patio",
"sauna",
"swimming pool",
"terrace",
"wi-fi"
]
}
}
}
},
"returns": {
"type": "string",
"description": "A list of properties"
},
"states": {
"reasoning": {
"description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
"instructions": [
"If the user mentions a city in their question, only search in that city by using the city parameter.",
"If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
"Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
"Determine if the response contains an error field.",
"If an error is present, provide the error code and error message from the JSON response to the user.",
"If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
]
}
}
},
{
"name": "saveSearch",
"description": "Save a search for properties for sale",
"parameters": {
"type" : "object",
"properties": {
"city": {
"type": "string",
"description": "The city to search in"
},
"bedrooms": {
"type": "number",
"description": "The number of bedrooms"
}
},
"required": [ "city" ]
},
"returns": {
"type": "string",
"description": "The unique ID for the saved search"
},
"states": {
"responding": {
"description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
"instructions": [
"Examine the output of the `saveSearch` function.",
"Extract the unique ID integer from the output and include it in your response to the user."
]
}
}
},
{
"name": "deleteSavedSearch",
"description": "Delete a previously saved search",
"parameters": {
"type" : "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique ID of the saved search"
}
},
"required": [ "id" ]
},
"returns": {
"type": "string",
"description": "True if the saved search was deleted, false otherwise"
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": { "type": "none" },
"run_for_functions": [ "getListings", "saveSearch", "deleteSavedSearch" ],
"spec": { "url": "http://contoso.com/openapi.yaml" }
}
],
"logo_url": "http://contoso.com/logo.png",
"contact_email": "contact@contoso.com",
"legal_info_url": "https://contoso.com/legal/",
}