Share via

Soporte de llamadas de API externas en Scripts de Office

  • Artículo

Los scripts admiten llamadas a servicios externos. Use estos servicios para proporcionar datos y otra información al libro.

Precaución

Las llamadas externas pueden dar lugar a la exposición de datos confidenciales a puntos de conexión no deseados. El administrador puede establecer Information Rights Management (IRM) o protección de firewall contra dichas llamadas.

Importante

Las llamadas a API externas solo se pueden realizar a través de la aplicación de Excel, no a través de Power Automate en circunstancias normales. Tampoco se admiten llamadas externas para scripts almacenados en un sitio de SharePoint.

Configuración del script para llamadas externas

Las llamadas externas son asincrónicas y requieren que el script esté marcado como async. Agregue el prefijo a main la async función y haga que devuelva un Promise, como se muestra aquí:

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

Nota:

Los scripts que devuelven otra información pueden devolver un Promise de ese tipo. Por ejemplo, si el script necesita devolver un Employee objeto, la firma de devolución sería : Promise <Employee>

Tendrá que aprender las interfaces del servicio externo para realizar llamadas a ese servicio. Si usa fetch o api rest, debe determinar la estructura JSON de los datos devueltos. Para la entrada y la salida del script, considere la posibilidad de crear una interface para que coincida con las estructuras JSON necesarias. Esto proporciona al script más seguridad de tipos. Puede ver un ejemplo de esto en Uso de la captura de scripts de Office.

Limitaciones con llamadas externas desde scripts de Office

  • No hay ninguna manera de iniciar sesión o usar flujos de autenticación de tipo OAuth2. Todas las claves y credenciales deben codificarse de forma rígida (o leerlas desde otro origen).
  • No hay ninguna infraestructura para almacenar las claves y las credenciales de API. El usuario tendrá que administrar esto.
  • No se admiten las cookies, localStoragey los sessionStorage objetos de documento.
  • Las llamadas externas pueden dar lugar a la exposición de datos confidenciales a puntos de conexión no deseados o a datos externos que se van a incluir en libros internos. El administrador puede establecer la protección del firewall frente a estas llamadas. Asegúrese de comprobar con las directivas locales antes de confiar en llamadas externas.
  • Asegúrese de comprobar la cantidad de rendimiento de datos antes de tomar una dependencia. Por ejemplo, extraer todo el conjunto de datos externo puede no ser la mejor opción y, en su lugar, se debe usar la paginación para obtener datos en fragmentos.

Recuperar información con fetch

La API de captura recupera información de servicios externos. Es una async API, por lo que debe ajustar la main firma del script. Haga que la main función async. También debe asegurarse de la awaitfetch llamada y json recuperación. Esto garantiza que esas operaciones se completen antes de que finalice el script.

Los datos JSON recuperados por fetch deben coincidir con una interfaz definida en el script. El valor devuelto debe asignarse a un tipo específico porque los scripts de Office no admiten el any tipo. Debe consultar la documentación del servicio para ver cuáles son los nombres y tipos de las propiedades devueltas. A continuación, agregue la interfaz o las interfaces coincidentes al script.

El siguiente script usa fetch para recuperar datos JSON del servidor de prueba en la dirección URL especificada. Tenga en cuenta la JSONData interfaz para almacenar los datos como un tipo coincidente.

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;
}

Otros fetch ejemplos

Restricción de llamadas externas con Information Rights Management (IRM)

Puede aplicar la configuración de IRM a un libro para evitar que los scripts realicen llamadas externas. Deshabilite la directiva Copy/EXTRACT para evitar este comportamiento.

Llamadas externas desde Power Automate

Se produce un error en las llamadas API externas cuando se ejecuta un script a través de Power Automate. Una fetch llamada mostrará el mensaje de error "Error en tiempo de ejecución: Línea X: la captura no está definida". Asegúrese de comprobar las referencias de los scripts antes de compilarlas en un flujo.

Tendrá que usar HTTP con Azure AD u otras acciones equivalentes para extraer datos o insertarlos en un servicio externo.

Advertencia

Se produce un error en las llamadas externas realizadas a través del conector de Excel Online de Power Automate para ayudar a mantener las directivas de prevención de pérdida de datos existentes. Sin embargo, los scripts que se ejecutan a través de Power Automate se realizan fuera de la organización y fuera de los firewalls de la organización. Para obtener protección adicional contra usuarios malintencionados en este entorno externo, el administrador puede controlar el uso de scripts de Office. El administrador puede deshabilitar el conector de Excel Online en Power Automate o desactivar Scripts de Office para Excel mediante los controles de administrador de Scripts de Office.

Vea también