Saltar a contenido

Microsoft 365 - Excel

Procesa y realiza operaciones en tus archivos de Excel en línea a través de una cuenta de Microsoft 365. Escribe, lee y actualiza tus hojas de cálculo fácilmente mediante el complemento de BotCity para Excel.

Warning

Para poder utilizar este complemento, necesitas tener una cuenta de Microsoft 365 con un proyecto creado y configurado correctamente.

Después de crear un proyecto, debes completar el proceso de autenticación a través del complemento de Credenciales de Microsoft 365.

Para más detalles, consulta las secciones anteriores:

Instalación

pip install botcity-ms365-excel-plugin

Importando el Complemento

Después de instalar este paquete, el siguiente paso es importar el paquete en tu código y comenzar a utilizar las funciones.

from botcity.plugins.ms365.excel import MS365ExcelPlugin

Configurando la cuenta de servicio

Como se mencionó anteriormente, para utilizar el complemento de Excel, es necesario realizar el proceso de autenticación de la cuenta a través del complemento de Credenciales de Microsoft 365.

Con la instancia del complemento de credenciales obtenida, vamos a utilizarla para instanciar el complemento de Excel.

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin, Scopes
from botcity.plugins.ms365.excel import MS365ExcelPlugin

# Instantiate the Credentials plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL])

# Instantiate the Excel plugin
excel = MS365ExcelPlugin(service_account=service)

Tip

Para utilizar el servicio de Excel, solo debes agregar el ámbito Scopes.FILES_READ_WRITE_ALL que se refiere al permiso Files.ReadWrite.All del proyecto.

Consulta más detalles sobre ámbitos y permisos en este enlace.

Obteniendo el archivo de Excel

El primer paso que debemos hacer para utilizar los servicios de Excel es configurar el archivo que se utilizará.

Este archivo de Excel debe estar almacenado en OneDrive al que tienes acceso con tu cuenta. Con eso en mente, podemos obtener la referencia del archivo de dos formas.

Utilizando la ruta del archivo en OneDrive

La forma más sencilla de buscar el archivo de Excel que se utilizará es pasar la ruta absoluta del archivo en OneDrive.

En este caso, se utilizará el OneDrive predeterminado de la cuenta como referencia.

Tip

La ruta del archivo debe seguir el patrón: '/ruta/al/archivo'.

El primer / significa que estamos comenzando desde la carpeta raíz, y el resto de la ruta será la "ruta absoluta" del elemento en el drive.

excel = MS365ExcelPlugin(service_account=service)

# Searching the Excel file using the file path in OneDrive
excel.get_excel_file(file_or_path="/documents/My-File.xlsx")

Utilizando el complemento de OneDrive para obtener el archivo

Si ya estás utilizando el complemento de OneDrive en tu código o por alguna otra razón, es preferible hacerlo de esta manera, también tienes la opción de obtener el archivo utilizando el complemento de OneDrive.

Utilizando uno de los métodos que devuelven un objeto File, puedes utilizar este objeto devuelto como parámetro del método get_excel_file.

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin, Scopes
from botcity.plugins.ms365.onedrive import MS365OneDrivePlugin
from botcity.plugins.ms365.excel import MS365ExcelPlugin

# Instantiate the Credentials plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL])

# Instantiate the OneDrive Plugin
onedrive = MS365OneDrivePlugin(service_account=service)

# Instantiate the Excel plugin
excel = MS365ExcelPlugin(service_account=service)

# Getting the Excel file using the OneDrive plugin
file = onedrive.get_file_by_name("My-File.xlsx")

# Setting the file to be used through the 'File' object
excel.get_excel_file(file_or_path=file)

Tip

Consulta más detalles sobre las formas de buscar archivos en el drive accediendo a la documentación del complemento de OneDrive.

Administrando hojas de cálculo

Podemos comenzar a realizar operaciones en las hojas de cálculo con el archivo de Excel configurado correctamente.

Utilizando el método get_excel_file, podemos pasar el nombre de la hoja de cálculo que se utilizará como referencia en las operaciones. Si no se pasa una hoja de cálculo específica, se utilizará por defecto la primera hoja de cálculo del archivo.

excel = MS365ExcelPlugin(service_account=service)

# Searching the Excel file and defining the active worksheet
excel.get_excel_file(file_or_path="/Test-Plugin.xlsx", active_sheet="Sheet2")

Obteniendo las hojas de cálculo existentes

Además de definir qué hoja de cálculo se utilizará al buscar el archivo de Excel, podemos listar todas las hojas de cálculo existentes o buscar una hoja de cálculo específica.

También podemos definir una nueva hoja de cálculo activa utilizando el objeto Worksheet devuelto o a través del nombre de la hoja de cálculo.

# Returning the list of worksheets
sheets = excel.list_sheets()

# Returning a specific Worksheet
results_sheet = excel.get_worksheet(sheet_name="Results")
# Defining the active sheet through the 'active_sheet' property
excel.active_sheet = results_sheet

# Another way to configure the active worksheet
excel.set_active_sheet("New Sheet")

Creando y eliminando hojas de cálculo

También puedes crear nuevas hojas en el archivo y eliminar hojas existentes.

# Removing a worksheet from the Excel file
excel.remove_sheet(sheet_name="Sheet2")

# Creating a new worksheet
excel.create_sheet(sheet_name="New Sheet")

Tip

Para poder utilizar una hoja que fue creada, debes utilizar el método set_active_sheet justo después de la creación.

Leyendo datos de la hoja de cálculo

Podemos obtener fácilmente el contenido de una hoja de cálculo de diferentes formas.

Podemos buscar una celda, una fila o una columna específica. Además, podemos obtener todo el contenido existente o incluso solo el contenido de un rango específico.

Warning

La API de Microsoft Graph utiliza algunos patrones para ciertos tipos de datos.

Si utilizas celdas con el formato Fecha en tus hojas de cálculo, recuerda que la API siempre devuelve estos valores en el patrón mm/dd/yyyy.

Por lo tanto, aunque utilices fechas en el formato dd/mm/yyyy, realiza los tratamientos necesarios al leer los datos utilizando el complemento.

Si es posible, recomendamos utilizar fechas en la hoja de cálculo en formato Texto para que la API devuelva el contenido sin aplicar patrones específicos.

# Returning the value of a specific cell
cell = excel.get_cell(column="B", row=2)
print(cell)

# Returning the values of a specific column
col = excel.get_column(column="A")
print(col)

# Returning the values of a specific row
row = excel.get_row(row=10)
print(row)

Al buscar todo el contenido de la hoja de cálculo, se devolverá una lista de listas, donde cada lista corresponderá a una fila de la hoja de cálculo.

# Returning all existing content in the worksheet in the format: List[List[object]]
values = excel.as_list()

# Each list corresponds to a row in the worksheet
for row in values:
    print(row)

# Returning the content of a given range of the worksheet
range_values = excel.get_range(range_="A1:E5")

# Each list corresponds to a row in the worksheet
for row in range_values:
    print(row)

Escribiendo nuevos datos

Para escribir nuevos datos en la hoja de cálculo, podemos utilizar la misma estrategia que utilizamos para leer.

Puedes ingresar datos en una sola celda o utilizar un rango específico de la hoja de cálculo.

Warning

La API de Microsoft Graph utiliza algunos patrones para ciertos tipos de datos.

Si utilizas números decimales, recomendamos utilizar . en lugar de , al ingresar los datos en la hoja de cálculo.

De esta manera, evitamos que la API aplique formatos no deseados a los valores utilizados.

# Entering data in a specific cell
excel.set_cell(column='L', row=7, value="Finished")

# Entering data in a specific range
# Each list represents a line that will be inserted
values = [
    ['Product', 'Stock', 'Price'],
    ['Notebook', '500', '1250.95'],
    ['Smartphone', '250', '700.99'],
    ['Mouse', '90', '65.25']
]

# The range used must be compatible with the size of the data list
excel.set_range(range_="A1:C4", values=values)

Además, también podemos insertar nuevas filas o columnas. Por defecto, estos nuevos valores se insertarán al final de la hoja de cálculo, pero también puedes utilizar un rango específico.

# Inserting a new row at the end of the worksheet
row = ["Keyboard", "380", "95.80"]
excel.add_row(row_values=row)

# Inserting a new column at the end of the worksheet
col = ["Seller", "John", "Maria"]
excel.add_column(column_values=col)

Eliminando datos

Además de leer y escribir datos en la hoja de cálculo, también podemos eliminar datos existentes.

Es posible borrar todo el contenido de la hoja de cálculo y eliminar valores de un rango o de una fila o columna específica.

Warning

Al utilizar los métodos para eliminar columnas, recuerda que cada columna eliminada hará que las columnas a su derecha se muevan hacia la izquierda.

Al utilizar los métodos para eliminar filas, recuerda que cada fila eliminada hará que las filas debajo de ella se muevan hacia arriba.

# Clearing all worksheet content
excel.clear()

# Clearing the values of a specific range
excel.clear(range_="B2:D10")

# Removing values from a single column
excel.remove_column(column="C")

# Removing values from specific columns
excel.remove_columns(columns=["F", "H", "J"])

# Removing values from a single row
excel.remove_row(row=15)

# Removing values from specific rows
excel.remove_rows(rows=[2, 4, 6])

Tip

Para todas las operaciones anteriores, puedes pasar la hoja de cálculo que se utilizará a través del parámetro worksheet.

En este caso, al pasar una hoja de cálculo como parámetro, se utilizará como referencia en el contexto del método en lugar de la hoja de cálculo activa actual.