Partager via

Prise en charge des appels d’API externes dans Scripts Office

  • Article

Les scripts prennent en charge les appels à des services externes. Utilisez ces services pour fournir des données et d’autres informations à votre classeur.

Attention

Les appels externes peuvent entraîner l’exposition de données sensibles à des points de terminaison indésirables. Votre administrateur peut établir la gestion des droits relatifs à l’information (IRM) ou la protection du pare-feu contre ces appels.

Importante

Les appels à des API externes ne peuvent être effectués que par le biais de l’application Excel, et non par le biais de Power Automate dans des circonstances normales. Les appels externes ne sont pas non plus pris en charge pour les scripts stockés sur un site SharePoint.

Configurer votre script pour les appels externes

Les appels externes sont asynchrones et nécessitent que votre script soit marqué comme async. Ajoutez le async préfixe à votre main fonction et faites-lui retourner un Promise, comme illustré ici :

async function main(workbook: ExcelScript.Workbook) : Promise <void>

Remarque

Les scripts qui retournent d’autres informations peuvent retourner un Promise de ce type. Par exemple, si votre script doit retourner un Employee objet, la signature de retour est : Promise <Employee>

Vous devez apprendre les interfaces du service externe pour effectuer des appels à ce service. Si vous utilisez fetchou des API REST, vous devez déterminer la structure JSON des données retournées. Pour l’entrée et la sortie de votre script, envisagez de créer un interface pour correspondre aux structures JSON nécessaires. Cela donne au script une plus grande sécurité de type. Vous pouvez voir un exemple de ceci dans Utilisation de la récupération à partir de scripts Office.

Limitations des appels externes à partir de scripts Office

  • Il n’existe aucun moyen de se connecter ou d’utiliser des flux d’authentification de type OAuth2. Toutes les clés et informations d’identification doivent être codées en dur (ou lues à partir d’une autre source).
  • Il n’existe aucune infrastructure pour stocker les informations d’identification et les clés d’API. Cela doit être géré par l’utilisateur.
  • Les cookies de sessionStorage document, localStorageet les objets ne sont pas pris en charge.
  • Les appels externes peuvent entraîner l’exposition de données sensibles à des points de terminaison indésirables ou à des données externes dans des classeurs internes. Votre administrateur peut établir une protection de pare-feu contre ces appels. Veillez à case activée avec des stratégies locales avant de vous appuyer sur des appels externes.
  • Veillez à case activée la quantité de débit de données avant de prendre une dépendance. Par instance, l’extraction de l’intégralité du jeu de données externe n’est peut-être pas la meilleure option. À la place, la pagination doit être utilisée pour obtenir des données en blocs.

Récupérer des informations avec fetch

L’API fetch récupère des informations à partir de services externes. Il s’agit d’une async API. Vous devez donc ajuster la main signature de votre script. Définissez la main fonction async. Vous devez également être sûr de l’appel await et json de la fetch récupération. Cela garantit que ces opérations se terminent avant la fin du script.

Toutes les données JSON récupérées par fetch doivent correspondre à une interface définie dans le script. La valeur retournée doit être affectée à un type spécifique, car les scripts Office ne prennent pas en charge le any type. Vous devez vous reporter à la documentation de votre service pour connaître les noms et les types des propriétés retournées. Ensuite, ajoutez l’interface ou les interfaces correspondantes à votre script.

Le script suivant utilise fetch pour récupérer des données JSON à partir du serveur de test dans l’URL donnée. Notez l’interface JSONData pour stocker les données en tant que type correspondant.

async function main(workbook: ExcelScript.Workbook) {
  // Retrieve sample JSON data from a test server.
  let fetchResult = await fetch('https://jsonplaceholder.typicode.com/todos/1');

  // Convert the returned data to the expected JSON structure.
  let json : JSONData = await fetchResult.json();

  // Display the content in a readable format.
  console.log(JSON.stringify(json));
}

/**
 * An interface that matches the returned JSON structure.
 * The property names match exactly.
 */
interface JSONData {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

Autres fetch exemples

Restreindre les appels externes avec la gestion des droits relatifs à l’information (IRM)

Vous pouvez appliquer des paramètres IRM à un classeur pour empêcher les appels externes effectués par des scripts. Désactivez la stratégie Copy/EXTRACT pour empêcher ce comportement.

Appels externes à partir de Power Automate

Les appels d’API externes échouent lorsqu’un script est exécuté via Power Automate. Un fetch appel donne le message d’erreur « Erreur d’exécution : Ligne X : l’extraction n’est pas définie ». Veillez à case activée vos scripts pour ces références avant de les générer dans un flux.

Vous devez utiliser HTTP avec Azure AD ou d’autres actions équivalentes pour extraire ou envoyer des données à un service externe.

Avertissement

Les appels externes effectués via le connecteur Excel Online Power Automate échouent pour aider à maintenir les stratégies de protection contre la perte de données existantes. Toutefois, les scripts exécutés via Power Automate le sont en dehors de votre organization et en dehors des pare-feu de votre organization. Pour une protection supplémentaire contre les utilisateurs malveillants dans cet environnement externe, votre administrateur peut contrôler l’utilisation des scripts Office. Votre administrateur peut désactiver le connecteur Excel Online dans Power Automate ou désactiver les scripts Office pour Excel via les contrôles d’administrateur scripts Office.

Voir aussi