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

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Objet runtime OpenAPI

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

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

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.

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.

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.

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.

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",
  "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/",
}

Voir aussi

• Plug-ins d’API pour Microsoft 365 Copilot