Microsoft 365 - Excel¶

Processe e execute operações em seus arquivos online do Excel por meio de uma conta do Microsoft 365. Escreva, leia e atualize suas planilhas facilmente através do plugin BotCity para o Excel.

Aviso

Para poder usar este plugin, você precisa ter uma conta do Microsoft 365 com um projeto criado e configurado corretamente.

Depois de criar um projeto, você precisa concluir o processo de autenticação por meio do plugin Microsoft 365 Credentials.

Para mais detalhes, consulte as seções anteriores:

Instalação¶

PythonJava

pip install botcity-ms365-excel-plugin

Importando o Plugin¶

Depois de instalar este pacote, a próxima etapa é importar o pacote no seu código e começar a usar as funções.

PythonJava

from botcity.plugins.ms365.excel import MS365ExcelPlugin

Configurando a conta de serviço¶

Conforme mencionado acima, para usar o plugin do Excel, é necessário realizar o processo de autenticação da conta por meio do plugin Microsoft 365 Credentials.

Com a instância do plugin de credenciais obtida, vamos usá-la para instanciar o plugin do Excel.

PythonJava

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

# Instanciando o plugin de Credenciais
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL])

# Instanciando o plugin do Excel
excel = MS365ExcelPlugin(service_account=service)

Dica

Para utilizar o serviço do Excel, basta adicionar o escopo Scopes.FILES_READ_WRITE_ALL referente à permissão Files.ReadWrite.All do projeto.

Veja mais detalhes sobre escopos e permissões nesse link.

Obtendo o arquivo Excel¶

O primeiro passo que temos que fazer para conseguir utilizar os serviços do Excel é configurar o arquivo que será utilizado.

Este arquivo do Excel deve estar armazenado em um OneDrive que você tenha acesso com a sua conta. Com isso em mente, podemos obter a referência do arquivo de duas maneiras.

Utilizando o caminho do arquivo no OneDrive¶

A forma mais simples de buscar pelo arquivo Excel que será utilizado é passando o caminho absoluto do arquivo no OneDrive.

Nesse caso, será utilizado como referência o OneDrive padrão da conta que está sendo usada.

Dica

O caminho do arquivo deve seguir o padrão: '/caminho/do/arquivo'.

A primeira / significa que estamos iniciando na pasta raiz e o restante do caminho será o "caminho absoluto" do item no drive.

PythonJava

excel = MS365ExcelPlugin(service_account=service)

# Buscando o arquivo Excel utilizando o caminho do arquivo no OneDrive
excel.get_excel_file(file_or_path="/documents/My-File.xlsx")

Utilizando o plugin do OneDrive para obter o arquivo¶

Se você já está utilizando o plugin do OneDrive no seu código, ou por algum outro motivo prefira fazer dessa maneira, você também tem a opção de obter o arquivo utilizando o plugin do OneDrive.

Utilizando um dos métodos que retorne um objeto File, você pode usar esse objeto retornado como parâmetro do método get_excel_file.

PythonJava

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

# Instanciando o plugin de Credenciais
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL])

# Instanciando o plugin do OneDrive
onedrive = MS365OneDrivePlugin(service_account=service)

# Instanciando o plugin do Excel
excel = MS365ExcelPlugin(service_account=service)

# Obtendo o arquivo Excel utilizando o plugin do OneDrive
file = onedrive.get_file_by_name("My-File.xlsx")

# Setando o arquivo que será utilizado através do objeto 'File'
excel.get_excel_file(file_or_path=file)

Dica

Veja mais detalhes sobre as formas de buscar arquivos no drive acessando a documentação do plugin do OneDrive.

Gerenciando planilhas¶

Com o arquivo Excel devidamente configurado, podemos começar a realizar as operações nas planilhas.

Ao usar o método get_excel_file podemos passar o nome da planilha que será usada como referência nas operações. Se nenhuma planilha específica for passada, será utilizada por padrão a primeira planilha do arquivo.

PythonJava

excel = MS365ExcelPlugin(service_account=service)

# Buscando o arquivo Excel e definindo a planilha ativa
excel.get_excel_file(file_or_path="/Test-Plugin.xlsx", active_sheet="Sheet2")

Buscando planilhas existentes¶

Além de definir qual planilha será utilizada ao buscar o arquivo Excel, também temos a possibilidade de listar todas as planilhas existentes ou buscar por uma planilha em específico.

Também podemos definir uma nova planilha ativa, usando o objeto Worksheet retornado ou através do nome da planilha.

PythonJava

# Retornando a lista de planilhas do arquivo
sheets = excel.list_sheets()

# Retornando uma Worksheet específica
results_sheet = excel.get_worksheet(sheet_name="Results")
# Definindo a planilha ativa através da propriedade 'active_sheet'
excel.active_sheet = results_sheet

# Outra forma para configurar a planilha ativa
excel.set_active_sheet("New Sheet")

Criando e removendo planilhas¶

Você também pode criar novas planilhas no arquivo e excluir planilhas existentes.

PythonJava

# Removendo planilha do arquivo Excel
excel.remove_sheet(sheet_name="Sheet2")

# Criando uma nova planilha
excel.create_sheet(sheet_name="New Sheet")

Dica

Para conseguir utilizar uma planilha que foi criada, você deve utilizar o método set_active_sheet logo após a criação.

Lendo dados da planilha¶

Conseguimos facilmente retornar o conteúdo de uma planilha de diferentes formas.

Podemos buscar por uma célula, linha ou coluna em específico. Além disso, podemos retornar todo o conteúdo existente ou até o contéudo somente de uma determinada área.

Tipos de formatos dos dados

A API do Microsoft Graph utiliza alguns padrões para determinados tipos de dados.

Se você utiliza nas suas planilhas células com o formato Date, tenha em mente que a API retorna esses valores sempre no padrão mm/dd/yyyy.

Então mesmo utilizando as datas no formato dd/mm/yyyy, certifique-se de fazer os tratamentos necessários ao ler os dados utilizando o plugin.

Recomendamos que, se possível, tente utilizar datas na planilha com o formato Texto, para que a API retorne o conteúdo sem aplicar padrões específicos.

PythonJava

# Retornando o valor de uma célula específica
cell = excel.get_cell(column="B", row=2)
print(cell)

# Retornando os valores de uma coluna específica
col = excel.get_column(column="A")
print(col)

# Retornando os valores de uma linha específica
row = excel.get_row(row=10)
print(row)

Ao buscar por todo o conteúdo da planilha, será retornado uma lista de listas, onde cada lista corresponderá a uma linha da planilha.

PythonJava

# Retornando todo o conteúdo existente na planilha no formato: List[List[object]]
values = excel.as_list()

# Cada lista corresponde a uma linha da planilha
for row in values:
    print(row)

# Retornando o conteúdo de um determinado range da planilha
range_values = excel.get_range(range_="A1:E5")

# Cada lista corresponde a uma linha da planilha
for row in range_values:
    print(row)

Escrevendo novos dados¶

Para escrevermos novos dados na planilha podemos utilizar a mesma estratégia que utilizamos para a leitura.

É possível inserir dados em uma única célula ou utilizar uma determinada área da planilha.

Tipos de formatos dos dados

A API do Microsoft Graph utiliza alguns padrões para determinados tipos de dados.

Caso utilize números com casas decimais, recomendamos utilizar . ao invés de , ao inserir os dados na planilha.

Dessa forma, evitamos que a API aplique alguma formatação indesejada para os valores que estão sendo utilizados.

PythonJava

# Inserindo dado em uma célula específica
excel.set_cell(column='L', row=7, value="Finished")

# Inserindo dados em um range específico
# Cada lista representa uma linha que será inserida
values = [
    ['Product', 'Stock', 'Price'],
    ['Notebook', '500', '1250.95'],
    ['Smartphone', '250', '700.99'],
    ['Mouse', '90', '65.25']
]

# O range utilizado deve ser compatível com o tamanho da lista dos dados
excel.set_range(range_="A1:C4", values=values)

Além disso, também podemos inserir novas linhas ou colunas. Por padrão, esses novos valores serão inseridos ao final da planilha, porém você também pode utilizar um range específico.

PythonJava

# Inserindo uma nova linha ao final da planilha
row = ["Keyboard", "380", "95.80"]
excel.add_row(row_values=row)

# Inserindo uma nova coluna ao final da planilha
col = ["Seller", "John", "Maria"]
excel.add_column(column_values=col)

Excluindo dados¶

Além de ler e escrever dados na planilha, também conseguimos remover dados existentes.

É possível limpar todo o conteúdo da planilha, remover os valores de uma área ou até de uma linha ou coluna em específico.

Aviso ao remover linhas ou colunas

Ao usar os métodos para remover colunas, lembre-se de que cada coluna removida fará com que as colunas à sua direita sejam movidas para a esquerda.

Ao usar os métodos para remover linhas, lembre-se de que cada linha removida fará com que as linhas abaixo dela sejam movidas para cima.

PythonJava

# Limpando todo o conteúdo da planilha
excel.clear()

# Limpando os valores de um range específico
excel.clear(range_="B2:D10")

# Removendo os valores de uma única coluna
excel.remove_column(column="C")

# Removendo os valores de colunas específicas
excel.remove_columns(columns=["F", "H", "J"])

# Removendo os valores de uma única linha
excel.remove_row(row=15)

# Removendo os valores de linhas específicas
excel.remove_rows(rows=[2, 4, 6])

Dica

Para todas as operações acima, você tem a possibilidade de passar a planilha que será utilizada através do parâmetro worksheet.

Nesse caso, ao passar uma planilha como parâmetro ela será usada como referência no contexto do método, ao invés da planilha ativa atual.