Partager via

Schéma de manifeste de plug-in d’API 2.1 pour Microsoft 365 Copilot

  • Article

Les plug-ins d’API permettent aux Microsoft 365 Copilot d’interagir avec les API REST décrites par une description OpenAPI. La description OpenAPI dans un plug-in d’API décrit les API REST avec lesquelles Copilot peut interagir. En outre, un plug-in d’API inclut un fichier manifeste de plug-in qui fournit des métadonnées sur le plug-in, telles que le nom, la description et la version du plug-in. Le manifeste du plug-in inclut également des informations sur les fonctionnalités du plug-in, telles que les API qu’il prend en charge et les opérations qu’il peut effectuer.

L’article suivant décrit le schéma 2.1 utilisé par les fichiers manifeste de plug-in d’API. Pour plus d’informations sur les plug-ins d’API, consultez Plug-ins d’API pour Microsoft 365 Copilot.

Importante

La dernière version du schéma de manifeste du plug-in d’API est la version 2.2. Nous recommandons aux nouveaux plug-ins d’utiliser la dernière version de schéma.

Schéma JSON

Le schéma décrit dans ce document se trouve au format de schéma JSONici.

Conventions

Références relatives dans les URL

Sauf indication contraire, toutes les propriétés qui sont des URL PEUVENT être des références relatives. Les références relatives dans le document manifeste sont relatives à l’emplacement du document manifeste.

Longueur de chaîne

Sauf indication contraire, toutes les propriétés de chaîne DOIVENT être limitées à 4 000 caractères. Cette longueur de chaîne ne confère aucune taille acceptable pour l’ensemble du document. Les implémentations sont libres d’imposer leurs propres limites pratiques sur la longueur du manifeste.

Propriétés non reconnues

Les objets JSON définis dans ce document prennent uniquement en charge les propriétés décrites. Les propriétés non reconnues dans n’importe quel objet JSON DOIVENT rendre l’intégralité du document non valide.

Localisation de chaîne

Les chaînes localisables peuvent utiliser une clé de localisation au lieu d’une valeur littérale. La syntaxe est [[key_name]], où key_name est le nom de clé dans la localizationKeys propriété dans vos fichiers de localisation. Pour plus d’informations sur la localisation, consultez Localiser votre agent.

Exemple de chaîne localisée

{
    "schema_version": "v2.1",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Objet manifeste de plug-in

La racine du document manifeste du plug-in est un objet JSON qui contient des propriétés qui décrivent le plug-in.

L’objet manifeste du plug-in contient les propriétés suivantes.

Propriété Type Description
schema_version String Obligatoire. Version du schéma. Les versions précédentes sont v1 et v2. Doit être défini sur v2.1.
name_for_human String Obligatoire. Nom court et lisible par l’utilisateur pour le plug-in. Il DOIT contenir au moins un caractère nonwhitespace. Les caractères au-delà de 20 PEUVENT être ignorés. Cette propriété est localisable.
namespace String Déconseillé. Optional.
description_for_model String Facultatif. Description du plug-in fourni au modèle. Cette description doit décrire à quoi sert le plug-in et dans quelles circonstances ses fonctions sont pertinentes. Les caractères au-delà de 2048 PEUVENT être ignorés. Cette propriété est localisable.
description_for_human String Obligatoire. Description lisible du plug-in. Les caractères au-delà de 100 PEUVENT être ignorés. Cette propriété est localisable.
logo_url String Facultatif. URL utilisée pour récupérer un logo qui PEUT être utilisé par l’orchestrateur. Les implémentations PEUVENT fournir d’autres méthodes pour fournir des logos qui répondent à leurs besoins visuels. Cette propriété est localisable.
contact_email String Facultatif. Adresse e-mail d’un contact pour la sécurité/modération, le support et la désactivation.
legal_info_url String Facultatif. URL absolue qui localise un document contenant les conditions d’utilisation du plug-in. Cette propriété est localisable.
privacy_policy_url String Facultatif. URL absolue qui localise un document contenant la politique de confidentialité du plug-in. Cette propriété est localisable.
functions Tableau de l’objet Function Optional. Ensemble d’objets de fonction décrivant les fonctions disponibles pour le plug-in. Chaque nom d’objet de fonction DOIT être unique dans le tableau. L’ordre du tableau n’est pas significatif. Si la functions propriété n’est pas présente et qu’il existe un runtime OpenAPI, les fonctions sont déduites à partir des opérations OpenAPI.
runtimes Tableau de l’objet runtime OpenAPI Optional. Ensemble d’objets runtime décrivant les runtimes utilisés par le plug-in.
capabilities Objet de fonctionnalités de plug-in Optional. Décrit les fonctionnalités du plug-in.

Objet Function

Informations relatives à la façon dont le modèle doit interagir avec une fonction.

L’objet de fonction contient les propriétés suivantes.

Propriété Type Description
id String Facultatif.
name String Obligatoire. Chaîne qui identifie de façon unique cette fonction. Les objets runtime PEUVENT référencer cet identificateur pour lier le runtime à la fonction . Lorsque la fonction est liée à un runtime OpenAPI, la valeur doit correspondre à une operationId valeur dans la description OpenAPI. La valeur doit correspondre à l’expression ^[A-Za-z0-9_]+$ régulière.
description String Facultatif. Description mieux adaptée au modèle, comme les considérations relatives à la longueur du contexte de jeton ou l’utilisation mot clé pour une invite de plug-in améliorée.
parameters Objet paramètres de fonction Optional. Objet qui contient des propriétés qui décrivent les paramètres d’une fonction de manière indépendante du runtime. Il reflète la forme de json-schema , mais ne prend en charge qu’un petit sous-ensemble des fonctionnalités de schéma JSON. Si la parameters propriété n’est pas présente, les fonctions décrites par un objet runtime de type OpenApi utilisent la description OpenAPI pour déterminer les paramètres. Chaque membre de l’objet JSON est un objet de paramètre de fonction qui décrit la sémantique du paramètre.
returns Objet de retour OR Objet de retour enrichi Optional. Décrit la sémantique de la valeur retournée par la fonction .
states Objet d’états de fonction Optional. Définit des objets d’état pour les états d’orchestrateur.
capabilities Objet fonctionnalités de fonction Optional. Contient une collection de données utilisée pour configurer les fonctionnalités facultatives de l’orchestrateur lors de l’appel de la fonction .

Exemple d’objet Function

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Objet paramètres de fonction

Objet utilisé pour identifier l’ensemble de paramètres qui peuvent être passés à la fonction. Cet objet est structuré pour miroir la forme d’un objet schéma JSON, mais il prend uniquement en charge un sous-ensemble de mots clés de schéma JSON.

L’objet de paramètres de fonction contient les propriétés suivantes.

Propriété Type Description
type String Facultatif. Type de schéma JSON. Doit être défini sur object.
properties Objet propriétés des paramètres de fonction Obligatoire. Objet qui mappe les noms de paramètres à leurs définitions.
required Tableau de chaînes Facultatif. Noms des propriétés qui sont des paramètres obligatoires. Contrairement au schéma JSON, les valeurs de ce tableau DOIVENT correspondre aux noms répertoriés dans la properties propriété .
Exemple d’objet paramètres de fonction
{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Objet propriétés des paramètres de fonction

Objet qui mappe les noms de paramètres à leurs définitions.

L’objet propriétés des paramètres de fonction contient les propriétés suivantes.

Propriété Type Description
Correspondance de nom ^[A-Za-z0-9_]+$ Objet de paramètre de fonction Optional. Définition de paramètre qui correspond au paramètre qui correspond au nom de la propriété.

Objet de paramètre de fonction

Objet qui décrit la sémantique d’un paramètre de fonction.

L’objet de paramètre de fonction contient les propriétés suivantes.

Propriété Type Description
type String Obligatoire. Spécifie le type du paramètre. Les valeurs possibles sont les suivantes : string, array, boolean, integer, number.
items Objet de paramètre de fonction Optional. Objet de paramètre de fonction qui décrit un élément unique dans un tableau. DOIT être présent uniquement lorsque type a la valeur array.
enum Tableau de chaînes Facultatif. Tableau de valeurs valides pour ce paramètre. DOIT être présent uniquement lorsque type a la valeur string.
description String Facultatif. Description du paramètre.
default Array, Boolean, String, Number, Integer Optional. Valeur du type spécifié par la type propriété qui indique la valeur utilisée par l’API lorsqu’aucune valeur n’est fournie pour un paramètre facultatif.
Exemple de paramètre de fonction
{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Objet de retour

Contient la sémantique de la valeur retournée par la fonction .

L’objet de retour contient les propriétés suivantes.

Propriété Type Description
type String Obligatoire. Spécifie le type de la valeur retournée par l’API. Les valeurs possibles sont : string.
description String Facultatif. Description de la valeur retournée par l’API.

Objet de retour enrichi

Indique que la fonction retourne une réponse compatible avec le protocole Rich Responses.

L’objet de retour enrichi contient les propriétés suivantes.

Propriété Type Description
$ref String Obligatoire. Doit être défini sur https://copilot.microsoft.com/schemas/rich-response-v1.0.json.

Objet d’états de fonction

Définit des objets d’état pour les états d’orchestrateur.

L’objet d’états de fonction contient les propriétés suivantes.

Propriété Type Description
reasoning Objet State Optional. État dans lequel le modèle peut appeler des fonctions et effectuer des calculs.
responding Objet State Optional. État dans lequel le modèle peut générer du texte affiché à l’utilisateur. Le modèle ne peut pas appeler des fonctions dans l’état de réponse.
disengaging Objet State Optional.

Objet State

Contient des instructions spécifiques quand une fonction est appelée dans un état d’orchestrateur spécifique.

L’objet state contient les propriétés suivantes.

Propriété Type Description
description String Facultatif. Décrit l’objectif d’une fonction lorsqu’elle est utilisée dans un état d’orchestrateur spécifique.
instructions Array, String Optional. Chaîne ou tableau de chaînes utilisées pour fournir des instructions à l’orchestrateur sur la façon d’utiliser cette fonction dans un état d’orchestrateur spécifique. La fourniture d’une chaîne unique indique l’intention de fournir un ensemble complet d’instructions qui remplaceraient toutes les invites de fonction intégrées. La fourniture d’un tableau de chaînes indique l’intention d’augmenter le mécanisme d’invite de fonction intégré.
examples Array, String Optional. Chaîne ou tableau de chaînes utilisées pour fournir des exemples à l’orchestrateur sur la façon dont cette fonction peut être appelée.
Exemple d’objet 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": []
        }
      }
    }
  ]
}

Objet fonctionnalités de fonction

Contient une collection de données utilisée pour configurer les fonctionnalités facultatives de l’orchestrateur lors de l’appel de la fonction .

L’objet de fonctionnalités de fonction contient les propriétés suivantes.

Propriété Type Description
confirmation Objet Confirmation Optional. Décrit une boîte de dialogue de confirmation qui DOIT être présentée à l’utilisateur avant d’appeler la fonction.
response_semantics Objet sémantique de réponse Optional. Décrit comment l’orchestrateur peut interpréter la charge utile de réponse et fournir un rendu visuel.

Objet Confirmation

Décrit comment l’orchestrateur demande à l’utilisateur de confirmer avant d’appeler une fonction.

L’objet de confirmation contient les propriétés suivantes.

Propriété Type Description
type String Facultatif. Spécifie le type de confirmation. Les valeurs possibles sont les suivantes : None, AdaptiveCard.
title String Facultatif. Titre de la boîte de dialogue de confirmation. Cette propriété est localisable.
body String Facultatif. Texte de la boîte de dialogue de confirmation. Cette propriété est localisable.

Objet sémantique de réponse

Contient des informations pour identifier la sémantique de la charge utile de réponse et permettre le rendu de ces informations dans une expérience visuelle enrichie à l’aide de cartes adaptatives.

L’objet sémantique de réponse contient les propriétés suivantes.

Propriété Type Description
data_path String Obligatoire. Une requête JSONPath RFC9535 qui identifie un ensemble d’éléments de la réponse de fonction à afficher à l’aide du modèle spécifié dans chaque élément.
properties Objet de propriétés de sémantique de réponse Optional. Autorise le mappage des requêtes JSONPath à des éléments de données connus. Chaque requête JSONPath est relative à une valeur de résultat.
static_template Objet Facultatif. Objet JSON conforme au schéma de carte adaptative et au langage de création de modèles. Cette instance de carte adaptative est utilisée pour afficher un résultat à partir de la réponse du plug-in. Cette valeur est utilisée si le template_selector n’est pas présent ou ne parvient pas à se résoudre en un carte adaptatif.
oauth_card_path String Facultatif.
Exemple de modèle statique
{
  "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}"
            }
          ]
        }
      }
    }
  }
}
Exemple de modèle dynamique
{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Objet de propriétés de sémantique de réponse

Autorise le mappage des requêtes JSONPath à des éléments de données connus. Chaque requête JSONPath est relative à une valeur de résultat.

L’objet de propriétés de sémantique de réponse contient les propriétés suivantes.

Propriété Type Description
title String Facultatif. Titre d’une citation pour le résultat.
subtitle String Facultatif. Sous-titre d’une citation pour le résultat.
url String Facultatif. URL d’une citation pour le résultat.
thumbnail_url String Facultatif. URL d’une image miniature pour le résultat.
information_protection_label String Facultatif. Indicateur de sensibilité des données du contenu du résultat.
template_selector String Facultatif. Une expression JSONPath vers une carte adaptative instance à utiliser pour le rendu du résultat.

Objet runtime OpenAPI

Décrit comment le plug-in appelle les fonctions OpenAPI.

L’objet runtime OpenAPI contient les propriétés suivantes.

Propriété Type Description
type String Obligatoire. Identifie ce runtime en tant que runtime OpenAPI. Doit être défini sur OpenApi.
auth Objet d’authentification runtime Obligatoire. Informations d’authentification requises pour appeler le runtime.
run_for_functions Tableau de chaînes Facultatif. Noms des fonctions disponibles dans ce runtime. Si cette propriété est omise, toutes les fonctions décrites par le runtime sont disponibles. Les valeurs de chaîne fournies peuvent contenir des caractères génériques. Plusieurs runtimes NE DOIVENT PAS déclarer la prise en charge de la même fonction implicitement ou explicitement.
spec Objet de spécification OpenAPI Obligatoire. Contient les informations OpenAPI requises pour appeler le runtime.

Objet de spécification OpenAPI

Contient les informations OpenAPI requises pour appeler le runtime.

L’objet de spécification OpenAPI contient les propriétés suivantes.

Propriété Type Description
url String Facultatif. URL permettant d’extraire la spécification OpenAPI, appelée avec une requête GET. Ce membre est obligatoire, sauf s’il api_description est présent.
api_description String Facultatif. Chaîne qui contient une description OpenAPI. Si ce membre est présent, url n’est pas obligatoire et est ignoré s’il est présent.
progress_style String Facultatif. Style de progression utilisé pour afficher la progression de la fonction. Les valeurs possibles sont les suivantes : None, ShowUsage, ShowUsageWithInput, ShowUsageWithInputAndOutput.
Exemple d’objet de spécification OpenAPI
{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}  

Objet d’authentification runtime

Contient des informations utilisées par le plug-in pour s’authentifier auprès du runtime.

L’objet d’authentification du runtime contient les propriétés suivantes.

Propriété Type Description
type String Facultatif. Spécifie le type d’authentification requis pour appeler une fonction. Les valeurs possibles sont None, OAuthPluginVault et ApiKeyPluginVault.
reference_id String Facultatif. Valeur utilisée quand type est OAuthPluginVault ou ApiKeyPluginVault. La reference_id valeur est acquise indépendamment lors de la fourniture des valeurs de configuration d’authentification nécessaires. Ce mécanisme existe pour éviter la nécessité de stocker des valeurs secrètes dans le manifeste du plug-in.
Exemple d’objet d’authentification du runtime
{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Objet de fonctionnalités de plug-in

Décrit les fonctionnalités du plug-in.

L’objet de fonctionnalités du plug-in contient les propriétés suivantes.

Propriété Type Description
conversation_starters Tableau de l’objet de démarrage de conversation Optional. Démarrages de conversation qui peuvent être affichés à l’utilisateur pour obtenir des suggestions sur la façon d’appeler le plug-in.

Objet de démarrage de conversation

Exemple de question à laquelle le plug-in peut répondre.

L’objet de démarrage de conversation contient les propriétés suivantes.

Propriété Type Description
text String Obligatoire. Texte du démarrage de la conversation. Cette propriété est localisable.
title String Facultatif. Titre du starter de conversation. Cette propriété est localisable.
Exemple d’objet de démarrage de conversation
{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Exemple de manifeste

Voici un exemple de fichier manifeste de plug-in qui utilise la plupart des propriétés de manifeste et des propriétés d’objet décrites dans l’article :

{
  "schema_version": "v2.1",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "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": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "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/"
}

Contenu connexe