Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Dans ce tutoriel, vous allez créer une compétence Copilot pour Excel qui utilise les API de la bibliothèque JavaScript Office (Office.js). La compétence recherche la première table dans la première feuille de calcul qui comporte au moins 12 colonnes et contient uniquement des données de corps numériques, puis trouve les lignes de cette table dont les données reflètent une tendance de croissance accélérée. Pour chaque ligne correspondante, il ajoute un graphique des données de lignes à la feuille de calcul.
Remarque
- Ce tutoriel part du principe que vous connaissez la vue d’ensemble des compétences Copilot pour Excel (préversion) et les plug-ins de génération pour Copilot Cowork. Bien que ce dernier article soit dans le contexte de Cowork, les conseils généraux relatifs à l’empaquetage, au manifeste, à l’icône, à l’installation et à la publication dans cet article s’appliquent également aux compétences Excel. Ce tutoriel se concentre sur les éléments propres à Excel et utilise le même modèle de package de plug-in que celui décrit dans cet article.
- Les compétences personnalisées pour Excel sont en préversion. Ne les utilisez pas dans une extension Copilot de production.
Ce que vous allez générer
Vous allez créer un package d’application Microsoft 365 avec une compétence.
my-copilot-plugin-skills/
|-- manifest.json
|-- color.png
|-- outline.png
|-- skills/
|-- accelerating-growth-trend-finder/
|-- SKILL.md
|-- resources/
| |-- workbook-data-guardrails.md
| |-- excel-vs-agent-execution.md
|-- scripts/
|-- find-accelerating-growth-trend-rows.js
Le script Office.js implémente l’analyse et la modification du classeur. Le SKILL.md fichier indique à Copilot quand utiliser le script et comment expliquer le résultat à l’utilisateur.
Définition de tendance à l’accélération de la croissance
Pour cette compétence, une ligne représente une tendance de croissance accélérée lorsque les deux éléments suivants sont vrais.
- Chaque valeur de cellule, en commençant par la deuxième colonne, est supérieure à la valeur immédiatement à gauche.
- Chaque augmentation, en commençant par l’augmentation de la deuxième cellule à la troisième cellule, est supérieure à l’augmentation précédente.
Par exemple, la ligne suivante est éligible.
2, 4, 8, 15, 27, 46, 78, 130, 215, 351, 570, 921
Les valeurs augmentent strictement, et la taille des augmentations augmente également strictement :
+2, +4, +7, +12, +19, +32, +52, +85, +136, +219, +351
Configuration requise
Avant de commencer, vérifiez que vous disposez de l’interface CLI microsoft 365 Agents Toolkit, comme décrit dans « Étape 7 : Test » des plug-ins de build pour Copilot Cowork.
Tâche 1 : Créer les dossiers de plug-in
Créez les dossiers suivants.
my-copilot-plugin-skills/
| -- skills/
| -- accelerating-growth-trend-finder/
| -- resources/
| -- scripts/
Tâche 2 : Créer SKILL.md
Dans le
skills/accelerating-growth-trend-finder/dossier , créez un fichier appeléSKILL.md.Ajoutez le frontmatter YAML suivant (y compris les deux
---lignes) tout en haut du fichier. Notez que lametadata.tagsvaleur inclutexcel, ce qui permet d’identifier la compétence comme étant orientée Excel à des fins de découverte des compétences.--- name: accelerating-growth-trend-finder description: | Use this skill in Excel when the user asks to find rows in a workbook table that show an accelerating growth, increasingly larger increases, or numeric values that rise faster from left to right. metadata: category: Excel analysis version: 1.0.0 tags: excel, office-js, tables, trends, analysis ---Importante
La valeur de la
namepropriété doit correspondre exactement au nom du dossier enfant directement sous leskillsdossier.Sous le frontmatter, ajoutez le markdown suivant pour concentrer Copilot sur l’objectif et les ressources de la compétence. Vous créez les deux fichiers de ressources à la dernière étape.
# Accelerating growth trend finder Find rows in the first qualifying Excel table whose numeric values increase from left to right with increasingly larger increases. ## Reference resources Before running the script, consult: - `resources/workbook-data-guardrails.md` - `resources/excel-vs-agent-execution.md` Use these resources to confirm that the current workbook is the right source of truth, that the skill is running inside Excel, and that the user is asking for workbook analysis rather than general advice.Sous les ressources, ajoutez la section de flux de travail suivante. Vous créez le fichier JavaScript qui appelle Office.js dans une étape ultérieure.
## Workflow 1. Confirm that the current context is Excel. 2. Run `scripts/find-accelerating-growth-trend-rows.js` when the user asks to identify rows with an accelerating growth trend.Sous le flux de travail, ajoutez les sections suivantes qui donnent des instructions sur la sortie. Notez que Copilot reconnaît quand JavaScript s’est terminé dans un état d’erreur et qu’il peut composer et signaler son propre message d’erreur, tel que « Aucune table éligible n’a été trouvée ». Toutefois, dans les scénarios où vous avez besoin que Copilot signale le message d’erreur exact retourné par le code, vous pouvez lui demander de le faire. La section sortie de conversation Copilot illustre les deux stratégies.
## Workbook output Let `scripts/find-accelerating-growth-trend-rows.js` create charts, but do not create new worksheets or formulas. ## Copilot chat output 1. For each chart that is created, report the table name and row that is the chart's source. 2. If there are no rows with an accelerating growth trend, report the problem. Use the exact error message that is returned by `scripts/find-accelerating-growth-trend-rows.js`. Do not reword it. 3. If there are any other problems, such as no qualifying tables, report the problem.Sous les instructions de sortie, ajoutez les conseils suivants à Copilot.
## Common pitfalls to avoid - Do not inspect tables outside the first worksheet. - Do not analyze a table unless it has at least 12 columns. - Do not treat the header row as numeric data. - Do not infer, coerce, or fill missing values. - Do not run the Office.js script outside Excel.
Tâche 3 : Ajouter des garde-fous de données de classeur
Dans le
skills/accelerating-growth-trend-finder/resourcesdossier, créez un fichier Markdown nomméworkbook-data-guardrails.md. Le fichier de ressources conserve les hypothèses de classeur spécifiques au scénario en dehors deSKILL.md, tout en donnant des garde-fous à Copilot pour quand il appelle le script.Donnez au fichier le contenu suivant.
# Workbook data guardrails Use this reference before running the accelerating growth trend script. ## Data requirements - Use only the first worksheet in the current workbook. - Use the first table on that worksheet that has at least 12 columns. - Ignore the table header row when checking whether the data is numeric. - Require every table body cell to contain a finite number. - Stop at the first table that satisfies the column-count and numeric-data requirements. ## Search rules - Do not search other worksheets. - Do not search loose ranges outside Excel tables. - Do not rename sheets, tables, or headers. - Do not create helper columns or formulas before running the script. ## Quality checks - If no table qualifies, report that no qualifying table was found. - If a table qualifies but no rows match, report that no rows in the qualifying table embody the trend. - Treat blank cells, text, errors, booleans, and dates that aren't returned as numbers as nonnumeric data. - If the user requests exponential trend data, report to the user that you will look for accelerating growth trend data, and that while all exponential trends are accelerating growth trends, the converse is not the case, so some of the trends you find may not be exponential.
Tâche 4 : Ajouter des conseils d’exécution Excel
Dans le
skills/accelerating-growth-trend-finder/resourcesdossier , créez un fichier Markdown nomméexcel-vs-agent-execution.md. Les règles de ce fichier sont nécessaires, car la compétence peut être accessible dans Copilot en dehors du contexte d’Excel, auquel cas les API Office.js ne peuvent pas s’exécuter. Si la compétence s’exécute en dehors d’Excel, Copilot ne doit pas prétendre qu’elle a analysé le classeur.Donnez-lui le contenu suivant.
# Excel vs non-Excel execution guidance ## When the skill runs inside Excel - Use the workbook as the source of truth. - Follow the instructions in the **Workflow**, **Workbook output**, and **Copilot chat output** sections of the SKILL.md file. ## When the skill runs outside Excel - Do not claim that workbook rows were analyzed. - Explain that the skill can only be used in Copilot in Excel. - Ask the user to open the workbook in Excel and invoke the skill there. ## When to use the scripts folder - Run `scripts/find-accelerating-growth-trend-rows.js` only when the user asks to find table rows with accelerating, or increasingly larger left-to-right growth. - Do not run the script for general explanations of accelerating growth growth. - Do not run the script when the current environment cannot execute Excel Office.js APIs.
Tâche 5 : Ajouter le script qui appelle Office.js
Dans le
skills/accelerating-growth-trend-finder/scriptsdossier , créez un fichier JavaScript nomméfind-accelerating-growth-trend-rows.js.Donnez au fichier le contenu suivant. Notez ce qui suit à propos de ce code.
- Le script se compose de la déclaration d’une seule fonction et il n’y a pas de code qui appelle la fonction. Copilot comprend que lorsque la compétence est appelée, elle doit appeler la fonction.
- Le script n’appelle
Office.onReadypas ou ne définitOffice.initializepas . Copilot crée le runtime, initialise Office.js et exécute des scripts de compétence. - Le script est conçu pour rechercher uniquement la première feuille de calcul. Cela permet de s’assurer que la compétence traite rapidement.
- Le script est conçu pour inspecter uniquement les tables qui répondent à certaines conditions. Il s’agit de fournir plusieurs chemins d’erreur pour illustrer différentes façons de gérer les erreurs.
- Le script appelle des méthodes d’assistance que vous créez dans les étapes ultérieures :
findFirstQualifyingTable,hasAcceleratingGrowthTrendetcreateAndPositionChart. - Si l’appel de
findFirstQualifyingTableretournenull, le script se termine par une instruction simplereturn;. Copilot reconnaît le problème et compose son propre message d’erreur. - Si aucune ligne avec une croissance accélérée n’est trouvée et qu’aucun graphique n’est créé, le script retourne un message d’erreur explicite. Le
SKILL.mdfichier indique à Copilot d’utiliser exactement ce message d’erreur. - La fonction est sans paramètre, car le classeur lui-même fournit toutes les entrées.
Remarque
La préversion des compétences basées sur Office.js ne prend pas en charge le passage de paramètres aux fonctions qui appellent Office.js. Nous travaillons d’arrache-pied pour fournir ce soutien à l’avenir.
await Excel.run(async (context) => { const firstWorksheet = context.workbook.worksheets.getFirst(); const tables = firstWorksheet.tables; tables.load("items"); await context.sync(); const tableInfo = await findFirstQualifyingTable(tables.items); if (!tableInfo) { return; } const { table: matchingTable, tableRange: matchingTableRange, dataRange: matchingDataRange } = tableInfo; let createdCharts = []; // Review each row in the qualifying table's data body. for (let rowOffset = 0; rowOffset < matchingDataRange.values.length; rowOffset += 1) { const row = matchingDataRange.values[rowOffset]; // If the row doesn't have an accelerating growth trend and there's another row, // check the next row. Otherwise, end the row checking loop without creating a chart. if (!hasAcceleratingGrowthTrend(row)) { continue; } // The row has an accelerating growth trend, so create a chart for it. await createAndPositionChart(firstWorksheet, matchingTable, matchingTableRange, matchingDataRange, rowOffset); createdCharts.push({ tableName: matchingTable.name, worksheetRowNumber: matchingDataRange.rowIndex + rowOffset + 1 }); } await context.sync(); if (createdCharts.length === 0) { return "No rows with an accelerating growth trend were found."; } return; });Ajoutez la méthode d’assistance suivante à la fin et à l’intérieur du rappel à
Excel.run. Notez que la méthode recherche la première table dans le tableau de tables fourni qui permet d’avoir une tendance significative. Une table éligible a :- Au moins 12 colonnes.
- Au moins une ligne de données.
- Toutes les valeurs numériques dans le corps des données.
async function findFirstQualifyingTable(tables) { for (const table of tables) { const tableRange = table.getRange(); const rows = table.rows; table.load("name"); tableRange.load(["columnCount", "rowIndex", "columnIndex", "rowCount"]); rows.load("count"); await context.sync(); if (tableRange.columnCount < 12 || rows.count === 0) { continue; } const dataRange = table.getDataBodyRange(); dataRange.load([ "values", "rowIndex", "rowCount", "columnCount"]); await context.sync(); const isEntirelyNumeric = dataRange.values.every((row) => row.every( (value) => typeof value === "number" && Number.isFinite(value) ) ); if (isEntirelyNumeric) { return { table, tableRange, dataRange }; } } return null; }Ajoutez la méthode d’assistance suivante à la fin et à l’intérieur du rappel à
Excel.run. Cette méthode détermine si une ligne a une tendance à l’accélération de la croissance.function hasAcceleratingGrowthTrend(row) { let previousIncrease = null; for (let columnIndex = 1; columnIndex < row.length; columnIndex += 1) { const increase = row[columnIndex] - row[columnIndex - 1]; if (increase <= 0 || (previousIncrease !== null && increase <= previousIncrease)) { return false; } previousIncrease = increase; } return true; }Ajoutez la méthode d’assistance suivante à la fin et à l’intérieur du rappel à
Excel.run. La méthode convertit un index de colonne de base zéro en lettres de colonne Excel. Les éléments suivants sont des exemples.- 0 -> A
- 1 -> B
- 25 -> Z
- 26 -> AA
function columnIndexToLetters(columnIndex) { let letters = ""; let n = columnIndex + 1; while (n > 0) { const remainder = (n - 1) % 26; letters = String.fromCharCode(65 + remainder) + letters; n = Math.floor((n - 1) / 26); } return letters; }Ajoutez la méthode d’assistance suivante à la fin et à l’intérieur du rappel à
Excel.run. La méthode crée et positionne un graphique en courbes pour une ligne de tableau correspondante. Notez ce qui suit à propos de ce code.- Le graphique est initialement basé sur la plage complète du tableau.
- Les séries pour les lignes qui ne correspondent pas sont ignorées.
- Le graphique est positionné d’une colonne à droite du tableau, est aligné verticalement avec la ligne de données correspondante et est dimensionné à 7 colonnes de large par 15 lignes de hauteur.
async function createAndPositionChart(worksheet, table, tableRange, dataRange, rowOffset) { // The worksheet row number, one-based, for the matching data row. const worksheetRowNumber = dataRange.rowIndex + rowOffset + 1; // ChartSeriesBy.rows means each data row becomes a chart series, // while the table headers provide the X-axis category labels. const chart = worksheet.charts.add(Excel.ChartType.line, tableRange, Excel.ChartSeriesBy.rows); chart.series.load("count"); await context.sync(); // Remove every series except the one for the matching row. for (let seriesIndex = chart.series.count - 1; seriesIndex >= 0; seriesIndex -= 1) { if (seriesIndex !== rowOffset) { chart.series.getItemAt(seriesIndex).delete(); } } chart.title.text = `${table.name} - Row ${worksheetRowNumber}`; chart.title.visible = true; // The only chart elements should be axes and gridlines. chart.legend.visible = false; chart.axes.categoryAxis.visible = true; chart.axes.valueAxis.visible = true; chart.axes.valueAxis.majorGridlines.visible = true; chart.axes.valueAxis.minorGridlines.visible = false; chart.dataLabels.showValue = false; chart.dataLabels.showCategoryName = false; chart.dataLabels.showSeriesName = false; // Position the chart one column to the right of the table. const chartStartColumn = tableRange.columnIndex + tableRange.columnCount + 1; // Align the chart's top edge with the matching data row. const chartStartRow = dataRange.rowIndex + rowOffset; // Make the chart 7 columns wide and 15 rows tall. const chartEndColumn = chartStartColumn + 6; const chartEndRow = chartStartRow + 14; const startCell = `${columnIndexToLetters(chartStartColumn)}${chartStartRow + 1}`; const endCell = `${columnIndexToLetters(chartEndColumn)}${chartEndRow + 1}`; chart.setPosition(startCell, endCell); }
Tâche 6 : Créer le manifeste
Créez un
manifest.jsonfichier dans le dossiermy-copilot-plugin-skillsracine .Donnez au fichier le contenu suivant. Vous ajoutez les deux fichiers d’icône dans une étape ultérieure.
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.29/MicrosoftTeams.schema.json", "manifestVersion": "1.29", "version": "1.0.0", "id": "00000000-0000-0000-0000-000000000000", "developer": { "name": "Contoso", "websiteUrl": "https://www.contoso.com", "privacyUrl": "https://www.contoso.com/privacy", "termsOfUseUrl": "https://www.contoso.com/terms" }, "name": { "short": "Accelerating Growth Trends", "full": "Accelerating Growth Trend Finder for Excel" }, "description": { "short": "Find Excel table rows with accelerating numeric growth.", "full": "A Copilot skill for Excel that uses Office.js to find rows in a workbook table where values increase from left to right with increasingly larger increases." }, "icons": { "color": "color.png", "outline": "outline.png" }, "accentColor": "#217346", }Remplacez la chaîne
1.29dans les deux premières lignes par le numéro de la dernière version du schéma de manifeste unifié Microsoft 365.Remplacez la valeur de l’espace réservé « id » par un GUID généré de manière aléatoire.
Remplacez les URL de développeur par les valeurs de votre application.
Ajoutez ce qui suit
"agentSkills"à l’objet racine."agentSkills": [ { "folder": "./skills/accelerating-growth-trend-finder" } ]
Remarque
Bien que la compétence appelle Office.js, vous n’avez pas besoin d’une "extensions" section dans le manifeste pour configurer un runtime. Copilot dans Excel crée le runtime et y charge Office.js.
Tâche 7 : Ajouter des icônes
Ajoutez les icônes de package requises dans le dossier my-copilot-plugin-skillsracine . Pour plus d’informations sur les exigences de taille des icônes, consultez « icônes ».
Conseil
Pour obtenir rapidement les fichiers requis, utilisez microsoft 365 Agent Toolkit pour créer n’importe quel type d’application pour Microsoft 365. Le projet créé contient le requis color.png et outline.png , généralement dans un dossier nommé assets. Copiez-les à la racine du projet de compétence.
Tâche 8 : Empaqueter la compétence
À partir de la my-copilot-plugin-skills racine, utilisez n’importe quel utilitaire ZIP pour créer un fichier ZIP qui contient le manifeste, les icônes et skills le dossier à la racine du fichier ZIP. Le fichier ZIP doit avoir la structure suivante.
|-- manifest.json
|-- color.png
|-- outline.png
|-- skills/
|-- accelerating-growth-trend-finder/
|-- SKILL.md
|-- resources/
|-- workbook-data-guardrails.md
|-- excel-vs-agent-execution.md
|-- scripts/
|-- find-accelerating-growth-trend-rows.js
Tâche 9 : Tester dans Excel
Installez le package en suivant les instructions de test dans « Étape 7 : Test » des plug-ins de build pour Copilot Cowork.
Créez ou ouvrez un classeur contenant au moins une table dans la première feuille de calcul qui remplit les conditions suivantes.
Contient une ligne d’en-tête.
Contient au moins 12 colonnes.
Contient uniquement des valeurs numériques dans le corps de la table. (La ligne d’en-tête peut contenir du texte.)
Contient au moins les lignes suivantes.
- Ligne qui remplit les deux conditions pour une tendance de croissance accélérée, comme défini précédemment dans La définition de la tendance de croissance accélérée.
- Ligne qui répond à la première condition, mais pas à la seconde.
- Ligne qui ne remplit aucune des conditions.
Voici un exemple des données d’une table qui convient pour le test.
Q1 T2 Q3 Q4 Q5 Q6 Q7 Q8 Q9 Q10 Q11 Q12 2 4 8 15 27 46 78 130 215 351 570 921 10 20 30 40 50 60 70 80 90 100 110 120 1 97 4018 22 98 506 83 0 5.7 -7 11 5 La première ligne répond aux critères, car les valeurs et les augmentations augmentent strictement. La deuxième ligne ne le fait pas, car les augmentations sont constantes. La troisième ne le fait pas, car les valeurs ne augmentent pas strictement.
Ouvrez Copilot dans Excel.
Vérifiez que votre compétence est installée en procédant comme suit.
Sélectionnez l’icône + dans la zone de conversation.
L’option Toutes les compétences dans la liste déroulante qui s’ouvre est d’abord désactivée. Attendez qu’elle soit activée, puis sélectionnez-la.
Dans la zone de texte de conversation, commencez à taper @accelerating-growth-trend-finder. La compétence doit apparaître dans la liste des compétences.
Retour arrière sur le nom pour effacer la conversation.
Dans la conversation, demandez à la compétence de rechercher les lignes de table avec une tendance de croissance accélérée. Quelque part dans votre invite, vous devez mention le nom complet de la compétence au format
@skill-name. Dans ce cas, utilisez@accelerating-growth-trend-finder. Les éléments suivants sont des exemples.@accelerating-growth-trend-finder, find rows in this workbook that show an accelerating growth trend.Find rows in this workbook that show an accelerating growth trend using @accelerating-growth-trend-finder.Copilot doit appeler la compétence, exécuter
find-accelerating-growth-trend-rows.js, créer des graphiques des lignes correspondantes et signaler les numéros de ligne de feuille de calcul correspondants à la conversation, comme pour les deux images suivantes. Les réponses de Copilot dans la conversation ne sont pas déterministes. Vous pouvez donc voir des différences par rapport à ce qui se trouve dans la capture d’écran ci-dessous et d’une exécution de l’outil à l’autre.
En haut se trouve l’invite de l’utilisateur qui indique « @accelerating-growth-trend-finder, recherchez les lignes de ce classeur qui montrent une tendance de croissance accélérée ». Ci-dessous, Copilot répertorie les quatre étapes principales qu’il a effectuées avec une description de chacune. Dans l’ordre, ils sont : '1. Vérification des règles d’analyse des classeurs. Passez en revue les conseils de compétence afin que la détection des tendances soit appliquée au tableau Excel actuel exactement comme prévu. 2. Préparation de la création de graphique. Le classeur est éligible pour l’analyse basée sur Excel demandée, et le script de la compétence crée des graphiques pour toutes les lignes correspondantes ; Je vérifie les conseils de graphique avant d’apporter ces modifications au classeur. 3. Recherche de lignes accélérées. Exécution de l’analyse du classeur sur la première table éligible et création d’un graphique pour chaque ligne dont les augmentations mensuelles augmentent chaque fois. 4. Création de graphiques de lignes correspondantes. Le script est prêt ; en l’appliquant à la feuille Sheet1 afin que le classeur affiche visuellement la ligne d’accélération de la croissance. » Sous cette description des étapes, Copilot résume ce qu’il a créé avec le texte « Graphique Créé 1 pour une tendance de croissance accélérée. Source : Sheet1 ! Tableau1, ligne Sheet1!2 (Sheet1 ! B2 :M2).'
Modifiez la table pour qu’elle ne soit pas éligible ; par exemple, réduisez le nombre de colonnes à moins de 12 ou placez des données non numériques dans l’une des cellules du corps du tableau.
Répétez votre invite à Copilot. Copilot doit composer son propre message d’erreur et le signaler dans la conversation.
Inversez vos modifications afin que la table soit à nouveau éligible.
Supprimez toutes les lignes dont la tendance de croissance s’accélère.
Répétez l’invite à Copilot. Copilot doit signaler le message d’erreur exact dans votre code : « Aucune ligne avec une tendance de croissance accélérée n’a été trouvée. »
Après chaque session de test, désinstallez la compétence en procédant comme suit.
Ouvrez Teams et assurez-vous que vous êtes connecté avec les mêmes informations d’identification que celles que vous avez utilisées pour installer la compétence.
Dans la barre de l’application Teams, sélectionnez le bouton Applications.
Dans le volet Applications , sélectionnez Gérer vos applications.
Recherchez le complément Accélération des tendances de croissance dans la liste des applications.
Sélectionnez le complément pour développer sa ligne.
Sélectionnez l’icône de corbeille, puis sélectionnez Supprimer dans l’invite.
Résolution des problèmes
| Problème | Cause probable | Corriger |
|---|---|---|
| La compétence ne se déclenche pas. | La demande de l’utilisateur ne correspond pas à la description de la compétence, ou le package de compétences n’est pas installé. | Suivez la procédure de désinstallation, puis réinstallez le package. |
| Copilot dit qu’il ne peut pas exécuter le script. | La compétence s’exécute en dehors d’Excel. | Ouvrez le classeur dans Excel et appelez la compétence. |
| La table incorrecte est analysée. | Un tableau précédent de la première feuille de calcul est également éligible. | Déplacez, renommez ou ajustez les tables afin que la table prévue soit la première table éligible. |