Excel Online
Use o conetor do Excel Online para realizar operações no Excel Online.
Antes de começar
Configure o seu projeto do Google Cloud, crie a sua aplicação OAuth e conceda as autorizações necessárias.Configure o projeto do Google Cloud
Antes de usar o conetor do Excel Online, conclua as seguintes tarefas no seu projeto do Google Cloud:
- Certifique-se de que a conetividade de rede está configurada. Para obter informações sobre padrões de rede, consulte o artigo Conetividade de rede.
- Ative os seguintes serviços:
secretmanager.googleapis.com
(Secret Manager API)connectors.googleapis.com
(API Connectors)
Para saber como ativar serviços, consulte o artigo Ativar serviços.
Se estes serviços ou autorizações não tiverem sido ativados anteriormente para o seu projeto, é-lhe pedido que os ative quando configurar o conector.
Crie uma aplicação OAuth personalizada – Azure AD
- Inicie sessão no portal do Azure.
- No painel de navegação do lado esquerdo, selecione Azure Active Directory e, de seguida, applicationRegistrations.
- Clique em Novo registo.
- Introduza um nome para a aplicação.
- Selecione a configuração de inquilino pretendida: único ou multi-inquilino, e utilização pública ou privada.
- Se selecionar a opção predefinida "Apenas contas neste diretório organizacional", tem de definir a propriedade de ligação AzureTenant para o ID do inquilino do Azure AD quando estabelecer uma ligação com o controlador JDBC da CData para o Microsoft Excel Online. Caso contrário, a tentativa de autenticação falha com um erro.
- Se a sua aplicação for apenas para utilização privada, especifique apenas contas neste diretório da organização.
- Se quiser distribuir a sua aplicação, escolha uma das opções multi-inquilino.
- Defina o URL de redirecionamento como http://localhost:33333 (a predefinição do controlador) OU especifique uma porta diferente e defina CallbackURL como o URL de resposta exato que definiu.
- Clique em Registar para registar a nova aplicação. É apresentado um ecrã de gestão de aplicações. Tenha em atenção o valor em ID da aplicação (cliente) como OAuthClientId e o ID do diretório (inquilino) como AzureTenant.
- Navegue para Certificados e segredos e defina o tipo de autenticação da aplicação. Estão disponíveis dois tipos de autenticação: certificado (recomendado) ou segredo do cliente.
- Para a autenticação por certificado: em Certificados e segredos, selecione Carregar certificado e, em seguida, carregue o certificado a partir do seu computador local.
- Para criar um novo segredo do cliente: em Certificados e segredos, selecione Novo segredo do cliente para a aplicação e especifique a respetiva duração. Depois de guardar o segredo do cliente, o Microsoft Excel Online apresenta o valor da chave. Copie este valor, uma vez que só é apresentado uma vez. Este valor torna-se o OAuthClientSecret.
- Selecione Autorizações da API > Adicionar > Autorizações delegadas.
- Adicione as seguintes autorizações da aplicação: Sites.Read.All, Files.Read, Files.Read.All, Files.Read.Selected, Files.ReadWrite, Files.ReadWrite.All, Files.ReadWrite.AppFolder, Files.ReadWrite.Selected e offline_access.
- Guarde as alterações.
- Se especificou a utilização de autorizações que requerem o consentimento do administrador (como as autorizações da aplicação), pode concedê-las a partir do inquilino atual na página Autorizações da API.
Crie uma aplicação OAuth personalizada: principal de serviço do Azure
- Use a barra de pesquisa para pesquisar o serviço Subscrições.
- Abra a página Subscrições.
- Selecione a subscrição à qual quer atribuir a aplicação.
- Abra o controlo de acesso (IAM).
- Selecione Adicionar > Adicionar atribuição de função. O Microsoft Excel Online abre a página Adicionar atribuição de função.
- Atribua à sua aplicação personalizada do Azure AD a função de proprietário.
Atribua uma função à aplicação
- Para aceder aos recursos na sua subscrição, tem de atribuir uma função à aplicação.
- Abra a página Subscrições pesquisando e selecionando o serviço Subscrições na barra de pesquisa.
- Selecione a subscrição à qual quer atribuir a aplicação.
- Abra o controlo de acesso (IAM) e selecione Adicionar > Adicionar atribuição de função para abrir a página Adicionar atribuição de função.
- Selecione Proprietário como a função a atribuir à app do Azure AD criada.
Conceda consentimento de administrador
- Inicie sessão no portal do Azure
- Navegue para Registo de apps e encontre a aplicação OAuth personalizada que criou.
- Em Autorizações da API, clique em Conceder consentimento.
Conceda autorizações para credenciais de cliente
- Inicie sessão no portal do Azure
- Navegue para Registos de apps.
- Encontre a aplicação que acabou de criar e abra Autorizações de API.
- Selecione as autorizações do Microsoft Graph. Existem dois conjuntos distintos de autorizações: delegadas e de aplicação.
- Em Autorizações da aplicação, selecione as autorizações necessárias para a sua integração.
Configure o conetor
Uma associação é específica de uma origem de dados. Isto significa que, se tiver muitas origens de dados, tem de criar uma associação separada para cada origem de dados. Para criar uma associação, faça o seguinte:
- Na Cloud Console, aceda à página Integration Connectors > Ligações e, de seguida, selecione ou crie um projeto do Google Cloud.
- Clique em + Criar novo para abrir a página Criar associação.
- Na secção Localização, escolha a localização para a ligação.
- Região: selecione uma localização na lista pendente.
As regiões suportadas para conetores incluem:
Para ver a lista de todas as regiões suportadas, consulte o artigo Localizações.
- Clicar em Seguinte.
- Região: selecione uma localização na lista pendente.
- Na secção Detalhes da associação, conclua o seguinte:
- Conetor: selecione Excel Online na lista pendente de conetores disponíveis.
- Versão do conetor: selecione a versão do conetor na lista pendente de versões disponíveis.
- No campo Nome da ligação, introduza um nome para a instância de ligação.
Os nomes das associações têm de cumprir os seguintes critérios:
- Os nomes das associações podem usar letras, números ou hífenes.
- As letras têm de ser minúsculas.
- Os nomes das associações têm de começar com uma letra e terminar com uma letra ou um número.
- Os nomes das associações não podem exceder 49 carateres.
- Opcionalmente, introduza uma Descrição para a instância de associação.
- Opcionalmente, ative o Registo na nuvem e, em seguida, selecione um nível de registo. Por predefinição, o nível do registo está definido como
Error
. - Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
- Opcionalmente, configure as definições do nó de associação:
- Número mínimo de nós: introduza o número mínimo de nós de ligação.
- Número máximo de nós: introduza o número máximo de nós de ligação.
Um nó é uma unidade (ou uma réplica) de uma ligação que processa transações. São necessários mais nós para processar mais transações para uma ligação e, inversamente, são necessários menos nós para processar menos transações. Para compreender como os nós afetam os preços dos conectores, consulte o artigo Preços dos nós de ligação. Se não introduzir valores, por predefinição, os nós mínimos são definidos como 2 (para uma melhor disponibilidade) e os nós máximos são definidos como 50.
- Inquilino do Azure: o inquilino online da Microsoft que está a ser usado para aceder aos dados. Se não for especificado, é usado o seu inquilino predefinido.
- Drive: o ID do disco. Pode usar as vistas Drives e SharePointSites para ver todos os sites e unidades aos quais tem acesso.
- URL do Sharepoint: o URL base do seu servidor Sharepoint.
- Mostrar documentos partilhados: se pretende ou não mostrar documentos partilhados.
- Livro: o nome ou o ID do livro.
- Cabeçalho: indica se os nomes das colunas devem ou não ser detetados a partir da primeira linha.
- Tabela: restringe a ligação a uma tabela que contém um intervalo de células de uma folha de cálculo. Formato: [{Workbook Name}_{Worksheet Name}!{Range}]
- Opcionalmente, clique em + Adicionar etiqueta para adicionar uma etiqueta à associação sob a forma de um par chave/valor.
- Clicar em Seguinte.
- Na secção Autenticação, introduza os detalhes de autenticação. Para saber como configurar estes detalhes de autenticação, consulte o artigo Configure a autenticação.
- Clicar em Seguinte.
- Rever: reveja os detalhes da ligação e da autenticação.
- Clique em Criar.
Configure a autenticação
Introduza os detalhes com base na autenticação que quer usar.
- ID de cliente: o ID de cliente usado para pedir tokens de acesso.
- Âmbito: uma lista separada por vírgulas dos âmbitos pretendidos.
- Segredo do cliente: o segredo do cliente usado para pedir tokens de acesso.
- URL de autorização: o URL de autorização que gera quando cria um cliente OAuth.
Introduza o URL no seguinte formato:
https://login.microsoftonline.com/AZURE_TENANT/oauth2/v2.0/authorize?prompt=consent
Excel Online – Tipo de ligação Web
Esta secção apresenta os valores de exemplo para os vários campos que configura quando cria a ligação do Excel Online.
Nome do campo | Detalhes |
---|---|
Localização | us-central1 |
Conetor | Excelonline |
Versão do conetor | 1 |
Nome da ligação | excelonline-gcp |
Conta de serviço | SERVICE_ACCOUNT_NAME@serviceaccount |
Inquilino do Azure | 9b******-****-****-****-*********12 |
Drive | b!p_648NCXwk6hJ1pfyn0SeFaithFnRM1JmYNur9asmHAs2k8qe5UsR5a1cX6luuD0 |
URL do Sharepoint | https://*****.sharepoint.com/ |
Mostrar documentos partilhados | True |
Número mínimo de nós | 2 |
Número máximo de nós | 50 |
ID do cliente | e89*****-****-****-****-*********b6 |
Âmbitos | https://graph.microsoft.com/.default |
Segredo do cliente | CLIENT_SECRET |
Versão do Secret | 1 |
URL de autorização | https://login.microsoftonline.com/AZURE_TENANT/oauth2/v2.0/authorize?prompt=consent |
Passos adicionais após a criação da associação
Se selecionou OAuth 2.0 - Authorization code
para a autenticação, tem de realizar os seguintes passos adicionais após criar a associação:
- Na página Ligações,
encontre a ligação criada recentemente.
Tenha em atenção que o Estado do novo conetor é Autorização necessária.
- Clique em Autorização obrigatória.
É apresentado o painel Editar autorização.
- Copie o valor do URI de redirecionamento para a sua aplicação externa.
- Valide os detalhes da autorização.
- Clique em Autorizar.
Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.
Nova autorização para o código de autorização
Se estiver a usar o tipo de autenticação Authorization code
e tiver feito alterações de configuração na sua aplicação Azure Synapse,
tem de voltar a autorizar a ligação do Azure Synapse. Para autorizar novamente uma associação, siga estes passos:
- Clique na associação necessária na página Associações.
É apresentada a página de detalhes da associação.
- Clique em Editar para editar os detalhes da associação.
- Valide os detalhes de OAuth 2.0 – Código de autorização na secção Autenticação.
Se necessário, faça as alterações necessárias.
- Clique em Guardar. Esta ação direciona para a página de detalhes da associação.
- Clique em Editar autorização na secção Autenticação. É apresentado o painel Autorizar.
- Clique em Autorizar.
Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.
Limitações do sistema
O tamanho máximo do ficheiro Excel que o conector do Excel Online pode processar é de 25 MB.
O conector do Excel Online pode processar 3 transações por segundo, por nó, e limita todas as transações que excedam este limite. Por predefinição, os Integration Connectors atribuem 2 nós (para uma melhor disponibilidade) a uma ligação.
Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.
Use a ligação do Excel Online numa integração
Depois de criar a ligação, esta fica disponível no Apigee Integration e no Application Integration. Pode usar a ligação numa integração através da tarefa Conectores.
- Para compreender como criar e usar a tarefa Connectors no Apigee Integration, consulte o artigo Tarefa Connectors.
- Para compreender como criar e usar a tarefa Connectors na integração de aplicações, consulte o artigo Tarefa Connectors.
Entidades, operações e ações
Todos os conetores de integração oferecem uma camada de abstração para os objetos da aplicação ligada. Só pode aceder aos objetos de uma aplicação através desta abstração. A abstração é exposta como entidades, operações e ações.
- Entidade: pode considerar uma entidade como um objeto ou uma coleção de propriedades na aplicação ou no serviço associado. A definição de uma entidade difere de um conetor para um conetor. Por exemplo, num conetor de base de dados, as tabelas são as entidades. Num conetor de servidor de ficheiros, as pastas são as entidades. Num conetor de sistema de mensagens, as filas são as entidades.
No entanto, é possível que um conector não suporte ou não tenha entidades, caso em que a lista
Entities
estará vazia. - Operação: uma operação é a atividade que pode realizar numa entidade. Pode realizar
qualquer uma das seguintes operações numa entidade:
Selecionar uma entidade na lista disponível gera uma lista de operações disponíveis para a entidade. Para uma descrição detalhada das operações, consulte as operações de entidades da tarefa de conectores. No entanto, se um conector não suportar nenhuma das operações de entidades, essas operações não suportadas não são apresentadas na lista
Operations
. - Ação: uma ação é uma função de primeira classe que é disponibilizada à integração
através da interface do conetor. Uma ação permite-lhe fazer alterações a uma ou mais entidades e
varia de conetor para conetor. Normalmente, uma ação tem alguns parâmetros de entrada e um parâmetro de saída. No entanto, é possível que um conector não suporte nenhuma ação, caso em que a lista
Actions
está vazia.
Ações
Esta secção apresenta as ações suportadas pelo conetor. Para compreender como configurar as ações, consulte os exemplos de ações.
Adicione a ação de folha de cálculo
Adiciona uma folha de cálculo a um livro existente do Excel Online.
Introduza os parâmetros da ação AddWorksheet
Nome do parâmetro | Tipo de dados | Obrigatória | Descrição |
---|---|---|---|
Título | String | True | Nome da folha de cálculo. |
WorkbookId | String | True | O ID do livro. Este ID tem de pertencer à unidade acessível com as propriedades de ligação atuais. |
Parâmetros de saída da ação AddWorksheet
Por exemplo, para saber como configurar a ação AddWorksheet
, consulte os exemplos.
Exemplos
Esta secção descreve como realizar algumas das ações neste conector.
Exemplos de ações
Esta secção descreve como realizar algumas das ações neste conector.
Exemplo: executar a ação AddWorksheet
Este exemplo adiciona uma folha de cálculo a um livro do Excel Online existente.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
AddWorksheet
e, de seguida, clique em Concluído. - Na secção Mapeamento de dados
Open Data Mapping Editor
e, de seguida, introduza um valor semelhante ao seguinte no campoInput
:{ "WorkbookId": "01M7ENMYA2QJVY77NPOFD3WQIJ6PNNX5VL", "Title": "Worksheet_SP1" }
Se a ação for bem-sucedida, o parâmetro de resposta da tarefa terá um valor semelhante ao seguinte:AddWorksheet
connectorOutputPayload
[{ "Success": "true", "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#workbookWorksheet", "@odata.type": "#microsoft.graph.workbookWorksheet", "@odata.id": "/drives('b%21p_648NCXwk6hJ1pfyn0SeFaithFnRM1JmYNur9asmHAs2k8qe5UsR5a1cX6luuD0')/items('01M7ENMYA2QJVY77NPOFD3WQIJ6PNNX5VL')/workbook/worksheets(%27%7BD9372F53-CB1B-4082-9E13-02E65C2FC233%7D%27)", "id": "{D9372F53-CB1B-4082-9E13-02E65C2FC233}", "name": "Worksheet_SP1", "position": "1", "visibility": "Visible" }]
Exemplos de operações de entidades
Esta secção mostra como realizar algumas das operações de entidades neste conector.
Exemplo: listar todos os discos
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Unidades na lista
Entity
. - Selecione a operação
List
e, de seguida, clique em Concluído.
Exemplo: listar todos os SharedDocuments
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione SharedDocuments na lista
Entity
. - Selecione a operação
List
e, de seguida, clique em Concluído.
Exemplo: listar todos os livros
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Livros de trabalho na lista
Entity
. - Selecione a operação
List
e, de seguida, clique em Concluído.
Exemplo: Get Drives
- Na caixa de diálogo
Configure connector task
, clique emEntities
.
ect Drives from the - Selecione a operação
Get
e, de seguida, clique em Concluído. - Defina o ID da entidade como Get single Drives. Para definir o ID da entidade, na secção Mapeador de dados do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e, em seguida, introduza
b!ZETdEU1T_UOBEzbgDmsvcubxvUaXbcJNrrNPM4LqokkwLC3zCRPiQLi2PBfCs9-v
no campo Valor de entrada e escolha EntityId como variável local.
Entity
list.
Exemplo: Get SharedDocument
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione SharedDocuments na lista
Entity
. - Selecione a operação
Get
e, de seguida, clique em Concluído. - Defina o ID da entidade para obter um único SharedDocument. Para definir o ID da entidade, na secção Mapeador de dados do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e, em seguida, introduza
01BDTL6TS3OQ3HDXCKGREILDYKY47S7LEI
no campo Valor de entrada e escolha EntityId como variável local.
Exemplo: Get Workbooks
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Livros de trabalho na lista
Entity
. - Selecione a operação
Get
e, de seguida, clique em Concluído. - Defina o ID da entidade para obter livros únicos. Para definir o ID da entidade, na secção Mapeador de dados do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e, em seguida, introduza
01M7ENMYA2QJVY77NPOFD3WQIJ6PNNX5VL
no campo Valor de entrada e escolha EntityId como variável local.
Exemplo: elimine dados do livro
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Book 4567_Sheet1 na
Entity
lista. - Selecione a operação
Delete
e, de seguida, clique em Concluído. - Defina o ID da entidade como Delete Book 4567_Sheet1. Para definir o ID da entidade, na secção Mapeador de dados do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e, em seguida, introduza
5.0
no campo Valor de entrada e escolha EntityId como variável local.
Exemplo: crie uma fórmula para Formulae_Sheet_List
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Formulae_Sheet_List na lista
Entity
. - Selecione a operação
Create
e, de seguida, clique em Concluído. - Na secção Mapeador de dados da Tarefa, clique no editor
OpenDataMapping
e, de seguida, introduza um valor semelhante ao seguinte nofield:
{ "Excel_Sheet": "Old_Excel", "B": "=SUM(C8:D8)", "C": "6", "D": "6" }
Running this example, returns a response similar to the following in the Connector task's
connectorOutputPayload
output variable:{ "Id": 8.0 }
Example - Create With_Headers
- In the
Configure connector task
dialog, clickEntities
. - Select Book 4567_Book4567_Sheet1 from the
Entity
list. - Select the
Create
operation, and then click Done. - In the Data mapper section of the Task click
OpenDataMapping
editor and then enter a value similar to the following in thefield:
Running this example, returns a response similar to the following in the Connector task's
connectorOutputPayload
output variable:{ "Id": 6.0 }
Example - Create Without_Headers
- In the
Configure connector task
dialog, clickEntities
. - Select Book 4567_Book4567_Sheet1 from the
Entity
list. - Select the
Create
operation, and then click Done. - In the Data mapper section of the Task click
OpenDataMapping
editor and then enter a value similar to the following in thefield:
Running this example, returns a response similar to the following in the Connector task's
connectorOutputPayload
output variable:{ "Id": 7.0 }
Example - Update an Formula for Formulae_Sheet_List
- In the
Configure connector task
dialog, clickEntities
. - Select Formulae_Sheet_List from the
Entity
list. - Select the
Update
operation, and then click Done. - Set the entity ID to Update a Formulae_Sheet_List. To set the entity ID, in
the Data mapper section of the Tasks, click entityId and
then enter
8.0
in the given field. - In the Data mapper section of the Task click
OpenDataMapping
editor and then enter a value similar to the following in thefield:
A execução deste exemplo devolve uma resposta semelhante à seguinte na variável de saída connectorOutputPayload
da tarefa do conector:
{ "Id": 8.0 }
Exemplo: atualização sem cabeçalho
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione Book 4567_Book4567_Sheet1 na
Entity
lista. - Selecione a operação
Update
e, de seguida, clique em Concluído. - Defina o ID da entidade para atualizar um livro 4567_Book4567_Sheet1. Para definir o ID da entidade, na secção Mapeador de dados das Tarefas, clique em entityId e, em seguida, introduza
7.0
no campo indicado. - Na secção Mapeador de dados da Tarefa, clique no editor
OpenDataMapping
e, de seguida, introduza um valor semelhante ao seguinte nofield:
{ "B": "cosmically", "C": "interlinked" }
A execução deste exemplo devolve uma resposta semelhante à seguinte na variável de saída connectorOutputPayload
da tarefa do conector:
{ "Id": 7.0 }
Exemplo: Update_With_Header
- Na caixa de diálogo
Configure connector task
, clique emEntities
.
li>Selecione Book 4567_Book4567_Sheet1 na lista - Selecione a operação
Update
e, de seguida, clique em Concluído. - Defina o ID da entidade para atualizar um livro 4567_Book4567_Sheet1. Para definir o ID da entidade, na secção Mapeamento de dados das Tarefas, clique em entityId e, em seguida, introduza
6.0
no campo indicado. - Na secção Mapeador de dados da Tarefa, clique no editor
OpenDataMapping
e, de seguida, introduza um valor semelhante ao seguinte nofield:
{ "Name": "updated", "Type": "newupdate" }
Entity
.
A execução deste exemplo devolve uma resposta semelhante à seguinte na variável de saída connectorOutputPayload
da tarefa do conector:
{ "Id": 6.0 }
Obtenha ajuda da comunidade do Google Cloud
Pode publicar as suas perguntas e discutir este conector na comunidade do Google Cloud nos Fóruns do Cloud.O que se segue?
- Compreenda como suspender e retomar uma associação.
- Compreenda como monitorizar a utilização do conector.
- Compreenda como ver os registos do conetor.