Excel Online

Use o conector do Excel Online para realizar operações no Excel Online.

Antes de começar

Configure seu projeto do Google Cloud, crie seu aplicativo OAuth e conceda as permissões necessárias.

Configurar o projeto do Google Cloud

Antes de usar o conector do Excel Online, faça o seguinte no seu projeto do Google Cloud:

• Ative os seguintes serviços:
  • secretmanager.googleapis.com (API Secret Manager)
  • connectors.googleapis.com (API Connectors)

  Para entender como ativar os serviços, consulte Como ativar serviços.

Se esses serviços ou permissões não tiverem sido ativados no seu projeto, você precisará ativá-los ao configurar o conector.

Criar aplicativo OAuth personalizado - Azure AD

1. Faça login no Portal do Azure.
2. No painel de navegação à esquerda, selecione Azure Active Directory e Registros de aplicativos.
3. Clique em "Novo registro".
4. Digite um nome para o aplicativo.
5. Selecione a configuração de locatário desejada: único ou multilocatário e uso público ou privado.
• Se você selecionar a opção padrão, "Contas apenas neste diretório organizacional", precisará definir a propriedade de conexão do AzureTenant como o ID do locatário do Azure AD ao estabelecer uma conexão com o driver CData JDBC para o Microsoft Excel Online. Caso contrário, a tentativa de autenticação falhará com um erro.
• Caso seu aplicativo seja apenas para uso particular, especifique as contas apenas neste diretório da organização.
• Se você quiser distribuir seu aplicativo, escolha uma das opções multiusuário.
6. Defina o URL de redirecionamento como http://localhost:33333 (o padrão do driver) OU especifique uma porta diferente e defina CallbackURL como o URL de resposta exato que você definiu.
7. Clique em "Registrar" para registrar o novo aplicativo. Uma tela de gerenciamento de aplicativos é exibida. Observe o valor no ID do aplicativo (cliente) como OAuthClientId e o ID do diretório (locatário) como AzureTenant.
8. Navegue até "Certificados e segredos" e defina o tipo de autenticação do aplicativo. Há dois tipos de autenticação disponíveis: certificado (recomendado) ou chave secreta do cliente.
• Para autenticação de certificado: em "Certificados e Secrets, selecione "Fazer upload do certificado" e faça upload do certificado pela máquina local.
• Para criar uma nova chave secreta do cliente: em "Certificados e chaves secretas", selecione "Nova chave secreta do cliente" para o aplicativo e especifique a duração. Depois que a chave secreta do cliente é salva, o Microsoft Excel Online exibe o valor da chave. Copie esse valor, porque ele é exibido apenas uma vez. Esse valor se torna o OAuthClientSecret.
9. Selecione "Permissões da API" > Adicionar > Permissões delegadas.
10. Adicione as seguintes permissões do aplicativo: 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.
11. Salve as alterações.
12. Se você especificou o uso de permissões que exigem o consentimento do administrador (como as permissões do aplicativo), pode concedê-las a partir do locatário atual na página "Permissões da API".

Criar um aplicativo OAuth personalizado: principal de serviço do Azure

1. Use a barra de pesquisa para procurar o serviço de Inscrições.
2. Abra a página "Assinaturas".
3. Selecione a assinatura para atribuir o aplicativo.
4. Abra o Controle de acesso (IAM).
5. Selecione "Adicionar" > "Adicionar atribuição de função". O Microsoft Excel Online abre a página "Adicionar atribuição de função".
6. Atribua a função de proprietário ao seu aplicativo personalizado do Azure AD.

Atribuir um papel ao aplicativo

1. Para acessar os recursos da sua assinatura, você precisa atribuir uma função ao aplicativo.
2. Abra a página de Assinaturas pesquisando e selecionando o serviço de Inscrições na barra de pesquisa.
3. Selecione a assinatura que será atribuída ao app.
4. Abra o controle de acesso (IAM) e selecione Adicionar > Adicionar atribuição de função para abrir a página "Adicionar atribuição de papel".
5. Selecione "Proprietário" como a função a ser atribuída ao app do Azure AD criado.

Conceder consentimento de administrador

1. Faça login no Portal do Azure.
2. Navegue até "Registros do app" e encontre o aplicativo OAuth personalizado que você criou.
3. Em Permissões da API, clique em Conceder consentimento.

Conceder permissões para credenciais de cliente

1. Faça login no Portal do Azure.
2. Acesse "Registros de apps".
3. Encontre o aplicativo que você acabou de criar e abra "Permissões da API".
4. Selecione as permissões do Microsoft Graph. Há dois conjuntos distintos de permissões: delegada e de aplicativo.
5. Em "Permissões do aplicativo", selecione as permissões necessárias para a integração.

Configurar o conector

Para configurar o conector, crie uma conexão com a fonte de dados (sistema de back-end). Uma conexão é específica a uma fonte de dados. Isso significa que, se você tiver muitas fontes de dados, precisará criar uma conexão separada para cada uma. Para criar uma conexão, siga estas etapas:

1. No console do Cloud, acesse a página Integration Connectors > Conexões e selecione ou crie um projeto do Google Cloud.

   Acessar a página "Conexões"

2. Clique em + Criar novo para abrir a página Criar conexão.
3. Na seção Local, escolha o local da conexão.
   1. Região: selecione um local na lista suspensa.

      Veja abaixo as regiões compatíveis com o conector:

      Para conferir a lista de todas as regiões com suporte, consulte Locais.

   2. Clique em Próxima.
4. Na seção Detalhes da conexão, faça o seguinte:
   1. Connector: selecione Excel Online na lista suspensa de conectores disponíveis.
   2. Versão do conector: selecione a versão do conector na lista suspensa de versões disponíveis.
   3. No campo Nome da conexão, insira um nome para a instância de conexão

      Os nomes de conexão precisam atender aos seguintes critérios:

      • Os nomes de conexões podem usar letras, números ou hifens.
      • As letras precisam ser minúsculas.
      • Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
      • Os nomes das conexões não podem ter mais de 49 caracteres.
   4. Como opção, insira uma Descrição para a instância de conexão.
   5. Como opção, ative o Cloud Logging e selecione um nível de registro. Por padrão, o nível de registro é definido como Error.
   6. Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
   7. Opcionalmente, defina as Configurações do nó de conexão:
      • Número mínimo de nós: digite o número mínimo de nós de conexão.
      • Número máximo de nós: digite o número máximo de nós de conexão.

      Um nó é uma unidade (ou réplica) de uma conexão que processa transações. Mais nós são necessários para processar mais transações para uma conexão e, por outro lado, menos nós são necessários para processar menos transações. Para entender como os nós afetam os preços do conector, consulte Preços dos nós de conexão. Se você não inserir qualquer valor, por padrão, os nós mínimos serão definidos como 2 (para melhor disponibilidade) e os nós máximos serão definidos como 50.

   Observação: você só poderá personalizar os valores do nó de conexão se for um cliente de pagamento por utilização.
   8. Locatário do Azure: o locatário do Microsoft Online usado para acessar dados. Se não for especificado, o locatário padrão será usado.
   9. Drive: o ID da unidade. Você pode usar as visualizações "Drives" e "SharePointSites" para acessar todos os sites e drives aos quais tem acesso.
   10. URL do SharePoint: o URL base do seu servidor do SharePoint.
   11. Mostrar documentos compartilhados: se os documentos compartilhados serão mostrados ou não.
   12. Pasta de trabalho: o nome ou ID da pasta de trabalho.
   13. Cabeçalho: indica se os nomes das colunas devem ou não ser detectados a partir da primeira linha.
   14. Tabela: restringe a conexão a uma tabela que contém um intervalo de células de uma planilha. Formato: [{Workbook Name}_{Worksheet Name}!{Range}]
   15. Outra opção é clicar em + Adicionar rótulo para adicionar um rótulo à conexão na forma de um par de chave-valor.
   16. Clique em Próxima.
5. 1. Na seção Autenticação, insira os detalhes da autenticação. Para entender como configurar esses detalhes de autenticação, consulte Configurar a autenticação.
   2. Clique em Próxima.
6. Revisão: revise os detalhes de conexão e autenticação.
7. Clique em Criar.

Configurar a autenticação

Digite os detalhes com base na autenticação que você quer usar.

• ID do cliente: o ID usado para solicitar tokens de acesso.
• Escopo: uma lista separada por vírgulas dos escopos desejados.
• Chave secreta do cliente: usada para solicitar tokens de acesso.
• URL de autorização: o URL de autorização gerado ao criar o cliente.

Excel Online: tipo de conexão da Web

Esta seção lista os valores de amostra para os vários campos que você configura ao criar a conexão do Excel Online.

Nome do campo	Detalhes
Local	us-central1
Conector	Excelonline
Versão do conector	1
Nome da conexão	excelonline-gcp
Conta de serviço	SERVICE_ACCOUNT_NAME@serviceaccount
Locatário do Azure	9b******-****-****-****-*********12
Drive	b!p_648NCXwk6hJ1pfyn0SeFaithFnRM1JmYNur9asmHAs2k8qe5UsR5a1cX6luuD0
URL do Sharepoint	https://*****.sharepoint.com/
Mostrar documentos compartilhados	Verdadeiro
Número mínimo de nós	2
Número máximo de nós	50
ID do cliente	e89*****-****-****-****-*********b6
Escopos	https://graph.microsoft.com/.default
Chave secreta do cliente	CLIENT_SECRET
Versão do secret	1
URL de autorização	https://login.microsoftonline.com/{Azure-Tenant}/oauth2/v2.0/authorize

Etapas adicionais após a criação da conexão

Se você selecionou OAuth 2.0 - Authorization code para siga estas etapas extras depois de criar a conexão:

1. Na página "Conexões", localize a conexão recém-criada.

   O Status do novo conector será Autorização necessária.

2. Clique em Autorização necessária.

   O painel Editar autorização será exibido.

3. Copie o valor do URI de redirecionamento para seu aplicativo externo.
4. Verifique os detalhes da autorização.
5. Clique em Autorizar.

   Se a autorização for bem-sucedida, o status da conexão será definido como Ativo na página "Conexões".

Reautorização do código de autorização

Se você estiver usando o tipo de autenticação Authorization code e tiver feito alterações de configuração no seu aplicativo do Azure Synapse, será necessário autorizar novamente a conexão do Azure Synapse. Para autorizar novamente uma conexão, siga estas etapas:

1. Clique na conexão necessária na página "Conexões".

   A página de detalhes da conexão será aberta.

2. Clique em Editar para editar os detalhes da conexão.
3. Verifique os detalhes de OAuth 2.0: código de autorização na seção Autenticação.

   Se necessário, faça as mudanças necessárias.

4. Clique em Salvar. Isso leva você à página de detalhes da conexão.
5. Clique em Editar autorização na seção Autenticação. Isso mostra o painel Autorizar.
6. Clique em Autorizar.

   Se a autorização for bem-sucedida, o status da conexão será definido como Ativo na página "Conexões".

Limitações do sistema

O tamanho máximo de arquivo do Excel que o conector do Excel Online pode processar é de 25 MB.

O conector do Excel Online pode processar três transações por segundo, por nó, e throttles as transações além desse limite. Por padrão, o Integration Connectors aloca dois nós para melhor disponibilidade para uma conexão.

Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.

Observação:o número de nós do Integration Connectors será escalonado automaticamente de maneira dinâmica com base no seu uso. No entanto, se você quiser reservar capacidade para grandes volumes sem esperar pelo escalonamento automático, ajuste o valor mínimo do nó para uma conexão. Mais nós são necessários para processar mais transações para uma conexão. Por outro lado, menos nós são necessários se uma conexão processa menos transações. Para configurar o nó , faça o seguinte:

• Se você for um cliente de pagamento por utilização, configure o valor mínimo e máximo do nó na página de edição de conexão.
• Se você tem uma assinatura entre em contato com o suporte.

O número máximo de transações que um nó pode processar depende de vários fatores. Portanto, antes de ajustar os nós mínimos para uma melhor taxa de transferência, recomendamos verificar se os sistemas de back-end estão configurados de maneira ideal para processar o tráfego necessário.

Usar a conexão do Excel Online em uma integração

Depois que você cria a conexão, ela fica disponível nos Apigee Integration e Application Integration. Você pode usar a conexão em uma integração pela tarefa Conectores.

• Para entender como criar e usar a tarefa Conectores na integração da Apigee, consulte a Tarefa Conectores.
• Para entender como criar e usar a tarefa "Conectores" na integração de aplicativos, consulte Tarefa "Conectores".

Entidades, operações e ações

Todos os Integration Connectors fornecem uma camada de abstração para os objetos do aplicativo conectado. Só é possível acessar os objetos de um aplicativo por esta abstração. A abstração é exposta a você como entidades, operações e ações.

Observação:você pode ver as entidades, as operações e as ações de um conector na tarefa de conectores.

• Entidade: uma entidade pode ser considerada um objeto ou um conjunto de propriedades no aplicativo ou serviço conectado. A definição de uma entidade difere de um conector para outro. Por exemplo, em um conector de banco de dados, as tabelas são as entidades, em um conector de servidor de arquivos, as pastas são as entidades e, em um conector de sistema de mensagens, as filas são as entidades.

  No entanto, é possível que um conector não aceite ou não tenha entidades. Nesse caso, a lista Entities estará vazia.

• Operação: uma operação é a atividade que pode ser realizada em uma entidade. É possível executar qualquer uma das seguintes operações em uma entidade:
  • Lista
  • Receber
  • Criar
  • Atualizar
  • Excluir

  Selecionar uma entidade na lista disponível gera uma lista de operações disponíveis para ela. Para uma descrição detalhada das operações, consulte as operações de entidades da tarefa "Conectores". No entanto, se um conector não oferecer suporte a nenhuma das operações de entidade, essas operações sem suporte não serão listadas na lista Operations.

• Ação: uma ação é uma função de primeira classe disponibilizada para a integração por meio da interface do conector. Uma ação permite fazer alterações em uma ou mais entidades e varia de um conector para outro. Normalmente, uma ação tem alguns parâmetros de entrada e um de saída. No entanto, é possível que o conector não ofereça suporte a nenhuma ação. Nesse caso, a lista Actions estará vazia.

Observação : todas as entidades e ações têm um esquema associado a elas. Por exemplo, um esquema de ação terá os detalhes do parâmetro, como: os nomes do parâmetro e tipos de dados correspondentes. O esquema (metadados) de entidades e ações é buscado pela conexão em do seu back-end. Se houver atualizações no esquema, elas não serão refletidas automaticamente nas suas conexões. Faça isso manualmente. Para atualizar o esquema de uma conexão, abra a página Detalhes da conexão e clique em Atualizar esquema de conexão.

Ações

Nesta seção, listamos as ações compatíveis com o conector. Para saber como configurar ações, consulte os Exemplos de ação.

Observação: os resultados de todas as ações vão estar disponíveis como uma resposta JSON no parâmetro de resposta connectorOutputPayload da tarefa Connectors após a execução da integração.

Ação de adicionar planilha

Adiciona uma planilha a uma pasta de trabalho do Excel Online.

Parâmetros de entrada da ação AddWorksheet

Nome do parâmetro	Tipo de dados	Obrigatório	Descrição
Título	String	Verdadeiro	Nome da planilha.
WorkbookId	String	Verdadeiro	O ID da pasta de trabalho. Esse ID precisa pertencer ao drive acessível com as propriedades de conexão atuais.

Parâmetros de saída da ação "AddWorksheet"

Por exemplo, sobre como configurar a ação AddWorksheet, consulte Exemplos.

Exemplos

Esta seção descreve como executar algumas das ações neste conector.

Exemplos de ação

Esta seção descreve como executar algumas das ações neste conector.

Exemplo: realizar a ação AddWorksheet

Este exemplo adiciona uma planilha a uma pasta de trabalho do Excel Online.

1. Na caixa de diálogo Configure connector task, clique em Actions.
2. Selecione a ação AddWorksheet e clique em Concluído.
3. Na seção Mapeamento de dados Open Data Mapping Editor e insira um valor semelhante ao seguinte no campo Campo Input:

   {   
   "WorkbookId": "01M7ENMYA2QJVY77NPOFD3WQIJ6PNNX5VL",
   "Title": "Worksheet_SP1"
   }

Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload da tarefa AddWorksheet terá um valor semelhante a este:

[{
  "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 entidade

Esta seção mostra como realizar algumas das operações de entidade neste conector.

Exemplo: listar todos os drives

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione "Drives" na lista Entity.
3. Selecione a operação List e clique em Concluído.

Exemplo: listar todos os SharedDocuments

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione SharedDocuments na lista Entity.
3. Selecione a operação List e clique em Concluído.

Exemplo: listar todas as abas

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione "Pastas de trabalho" na lista Entity.
3. Selecione a operação List e clique em Concluído.

Exemplo: receber trajetos

1. Na caixa de diálogo Configure connector task, clique em Entities.
e etc. "Drives" na lista Entity.
2. Selecione a operação Get e clique em Concluído.
3. Defina o ID da entidade como "Get single drive". Para definir o ID da entidade, em Na seção Mapeador de dados de Mapeamento de dados, clique em Abrir editor de mapeamento de dados e Em seguida, insira b!ZETdEU1T_UOBEzbgDmsvcubxvUaXbcJNrrNPM4LqokkwLC3zCRPiQLi2PBfCs9-v no campo Valor de entrada e escolha "EntityId" como a variável local.

Exemplo: acessar SharedDocument

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione SharedDocuments na lista Entity.
3. Selecione a operação Get e clique em Concluído.
4. Defina o ID da entidade como "Get single SharedDocument". Para definir o ID da entidade, em Na seção Mapeador de dados de Mapeamento de dados, clique em Abrir editor de mapeamento de dados e Em seguida, insira 01BDTL6TS3OQ3HDXCKGREILDYKY47S7LEI no campo Valor de entrada e escolha "EntityId" como a variável local.

Exemplo: Receber pastas de trabalho

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione "Cadernos de trabalho" na lista Entity.
3. Selecione a operação Get e clique em Concluído.
4. Defina o ID da entidade como "Recuperar planilhas". Para definir o ID da entidade, na seção Data Mapper do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e digite 01M7ENMYA2QJVY77NPOFD3WQIJ6PNNX5VL no campo Valor de entrada e escolha o EntityId como variável local.

Exemplo: excluir dados do livro

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione Book 4567_Sheet1 na lista Entity.
3. Selecione a operação Delete e clique em Concluído.
4. Defina o ID da entidade como Excluir livro 4567_Sheet1. Para definir o ID da entidade, na seção Data Mapper do Mapeamento de dados, clique em Abrir editor de mapeamento de dados e digite 5.0 no campo Valor de entrada e escolha o EntityId como variável local.

Exemplo: criar uma fórmula para Formulae_Sheet_List

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione Formulae_Sheet_List na lista Entity.
3. Selecione a operação Create e clique em Concluído.
4. Na seção Mapeador de dados da Tarefa, clique em OpenDataMapping e insira um valor semelhante ao seguinte no field:

    {
     "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

1. In the Configure connector task dialog, click Entities.
2. Select Book 4567_Book4567_Sheet1 from the Entity list.
3. Select the Create operation, and then click Done.
4. In the Data mapper section of the Task click OpenDataMapping editor and then enter a value similar to the following in the field:

    {
       "Name": "workbooknew",
       "Type": "newly created",
       "Sl no": 5.0
     }
     
   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

1. In the Configure connector task dialog, click Entities.
2. Select Book 4567_Book4567_Sheet1 from the Entity list.
3. Select the Create operation, and then click Done.
4. In the Data mapper section of the Task click OpenDataMapping editor and then enter a value similar to the following in the field:

     {
       "A": "6",
       "B": "Halo",
       "C": "Stardust"
     } 
     
   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

1. In the Configure connector task dialog, click Entities.
2. Select Formulae_Sheet_List from the Entity list.
3. Select the Update operation, and then click Done.
4. 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.
5. In the Data mapper section of the Task click OpenDataMapping editor and then enter a value similar to the following in the field:

    
     {
     "B": "=MAX(C8:D8)",
     "C": "7",
     "D": "10"
     } 
     

A execução desse exemplo retorna uma resposta semelhante a esta na variável de saída connectorOutputPayload da tarefa do conector:

 
  {   
  "Id": 8.0
  }
  

Exemplo: atualização sem_Header

1. Na caixa de diálogo Configure connector task, clique em Entities.
2. Selecione Book 4567_Book4567_Sheet1 na lista Entity.
3. Selecione a operação Update e clique em Concluído.
4. Defina o ID da entidade como Atualizar um livro 4567_Book4567_Sheet1. Para definir o ID da entidade, na seção Data Mapper das Tarefas, clique em entityId e insira 7.0 no campo fornecido.
5. Na seção Mapeador de dados da Tarefa, clique em OpenDataMapping e insira um valor semelhante ao seguinte no field:

    
      {
       "B": "cosmically",
       "C": "interlinked"
     }  
     

A execução deste exemplo retorna uma resposta semelhante à seguinte no conector variável de saída connectorOutputPayload da tarefa:

 
  {   
  "Id": 7.0
  }
  

Exemplo: Update_With_Header

1. Na caixa de diálogo Configure connector task, clique em Entities.
li>Selecione "Livro 4567_Book4567_Sheet1" na lista Entity.
2. Selecione a operação Update e clique em Concluído.
3. Defina o ID da entidade para "Atualizar um livro" 4567_Book4567_Sheet1. Para definir o ID da entidade, na seção Data Mapper das Tarefas, clique em entityId e digite 6.0 no campo.
4. Na seção Data Mapper da Tarefa, clique no editor OpenDataMapping e insira um valor semelhante ao seguinte no field::

    
      {
       "Name": "updated",
       "Type": "newupdate"
     }
     

A execução deste exemplo retorna uma resposta semelhante à seguinte no conector variável de saída connectorOutputPayload da tarefa:

 
  {   
  "Id": 6.0
  }
  

Receber ajuda da comunidade do Google Cloud

Poste suas dúvidas e converse sobre esse conector na comunidade do Google Cloud em Fóruns do Cloud.

A seguir

• Entenda como suspender e retomar uma conexão.
• Entenda como monitorar o uso do conector.
• Saiba como acessar os registros do conector.