Associe o Microsoft OneDrive à carregamento de dados

Esta página descreve como associar o Microsoft OneDrive ao Gemini Enterprise através do carregamento de dados.

Use o procedimento seguinte para sincronizar dados do OneDrive.

Depois de configurar a origem de dados e importar dados pela primeira vez, o armazenamento de dados sincroniza os dados dessa origem com uma frequência que seleciona durante a configuração.

Limitações

A sincronização incremental não deteta ações ao nível da pasta, como Copiar, Mover ou Mudar o nome.

Antes de começar

Para aplicar o controlo de acesso à origem de dados e proteger os dados no Gemini Enterprise, certifique-se de que configurou o seu fornecedor de identidade.

Acerca do registo de aplicações do Microsoft Entra ID

Antes de poder criar o conector no Gemini Enterprise, tem de configurar um registo de aplicação do Microsoft Entra ID para permitir o acesso seguro ao OneDrive. A forma como regista a aplicação depende do método de autenticação que seleciona quando cria o conector no Gemini Enterprise. Pode escolher um dos seguintes métodos:

  • Credenciais federadas:

    • Permite que a Google aceda de forma segura ao OneDrive através de tokens assinados criptograficamente, evitando a necessidade de um principal de utilizador real.

    • Requer um ID do assunto para registar o Gemini Enterprise no Entra. Esta opção está disponível quando cria o conector do OneDrive no Gemini Enterprise.

    • Quando regista a sua app no Entra ID, tem de reunir os seguintes detalhes:

      • URI da instância:
        • Para todos os sites de primeiro nível: https://DOMAIN_OR_SERVER.onedrive.com —por exemplo, mydomain.onedrive.com.
        • Para um único site: https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE —por exemplo, mydomain.onedrive.com/sites/sample-site.
      • ID do inquilino
      • ID do cliente

      Estes detalhes são necessários para concluir a autenticação e criar o conector do OneDrive no Gemini Enterprise.

    • A Google recomenda que use este método.

  • Token de atualização do OAuth 2.0:

    • Oferece um controlo detalhado sobre quem se liga à API OneDrive.

    • Quando regista a sua app no Entra ID, tem de reunir os seguintes detalhes:

      • URI da instância: tem o seguinte formato:
        • Para todos os sites de primeiro nível: https://DOMAIN_OR_SERVER.onedrive.com —por exemplo, mydomain.onedrive.com.
        • Para um único site: https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE —por exemplo, mydomain.onedrive.com/sites/sample-site.
      • ID do inquilino
      • ID do cliente
      • Segredo do cliente

      Estes detalhes são necessários para concluir a autenticação e criar o repositório de dados do OneDrive no Gemini Enterprise.

    • O processo de autenticação inclui o início de sessão na sua conta do OneDrive.

    • Este método é adequado quando a configuração do OneDrive requer uma autenticação de dois fatores.

    • Requer a criação de um novo utilizador do OneDrive, o que pode adicionar custos de licenciamento.

  • Concessão de palavra-passe do OAuth 2.0:

    • Oferece controlo detalhado sobre quem se liga à API OneDrive.

    • Quando regista a sua app no Entra ID, tem de reunir os seguintes detalhes:

      • URI da instância:
        • Para todos os sites de primeiro nível: https://DOMAIN_OR_SERVER.onedrive.com —por exemplo, mydomain.onedrive.com.
        • Para um único site: https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE —por exemplo, mydomain.onedrive.com/sites/sample-site.
      • ID do inquilino
      • ID do cliente
      • Segredo do cliente

      Estes detalhes são necessários para concluir a autenticação e criar o repositório de dados do OneDrive no Gemini Enterprise.

    • O processo de autenticação inclui o fornecimento do nome de utilizador e da palavra-passe fornecidos pelo administrador do Entra ID.

    • Este método é adequado quando a configuração do OneDrive não requer uma autenticação de dois fatores.

    • Este método requer que crie um novo utilizador do OneDrive, o que pode adicionar custos de licenciamento.

Configure credenciais federadas

Siga os passos abaixo para configurar o registo da app, conceder autorizações e estabelecer a autenticação. A Google recomenda que use o método de credenciais federadas.

Algumas mensagens de erro comuns que pode encontrar durante este processo estão listadas em Mensagens de erro.

  1. Obtenha o ID de cliente da conta de serviço:

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.
    2. No menu de navegação, clique em Armazenamentos de dados.
    3. Clique em Criar arquivo de dados.
    4. Na página Selecione uma origem de dados, desloque a página ou pesquise OneDrive para associar a sua origem de terceiros.
    5. Tome nota do identificador do assunto. Não clique já em Continuar. Execute os passos seguintes nesta tarefa e, em seguida, conclua os passos na Google Cloud consola seguindo as instruções em Crie um conetor do OneDrive.
  2. Registe a app no Entra ID:

    1. Navegue para o centro de administração do Microsoft Entra.
    2. No menu, expanda a secção Aplicações e selecione Registos de apps.
    3. Na página Registos de apps, selecione Novo registo.

      Registe uma nova app no Entra
      Registe uma nova app no centro de administração do Microsoft Entra

    4. Crie um registo de app na página Registar uma aplicação:

      • Na secção Tipos de contas suportados, selecione Contas apenas no diretório organizacional.
      • Na secção URI de redirecionamento, selecione Web e introduza o URI de redirecionamento https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html
      • Mantenha os valores predefinidos para as outras definições e clique em Registar.

      Registar contas apenas no diretório organizacional
      Selecione o tipo de conta e introduza o URI de redirecionamento

    5. Anote o ID do cliente e o ID do inquilino.

      Resumo da página de detalhes da app
      Página de detalhes da app

  3. Adicione credenciais federadas:

    1. Aceda a Certificados e segredos > Credenciais federadas > Adicionar credencial.

      Adicione credenciais federadas no Entra
      Adicione credenciais federadas no Microsoft Entra

    2. Use as seguintes definições:

      • Cenário de credenciais federadas: outro emissor

      • Emissor: https://accounts.google.com

      • Identificador do assunto: use o valor do Identificador do assunto que anotou no passo anterior.

      • Nome: indique um nome exclusivo.

    3. Clique em Adicionar para conceder acesso.

      Associe a sua Conta Google ao Microsoft Entra ID
      Associe a sua Conta Google ao Microsoft Entra ID

  4. Defina as autorizações da API.

    Selecione a app para definir autorizações da API
    Selecione a app para definir autorizações da API

    1. Adicione e conceda as seguintes autorizações do Microsoft Graph. Pode escolher entre as opções de controlo do site (Sites.FullControl.All e Sites.Selected) e as opções de leitura de perfis (User.Read.All e User.ReadBasic.All):

      Autorizações da API Microsoft Graph para credenciais federadas

      Autorização Tipo Descrição Justificação
      GroupMember.Read.All Aplicação Ler todos os membros do grupo Esta autorização permite que o Gemini Enterprise compreenda as associações dos grupos de utilizadores no site do OneDrive.
      User.Read Delegada Inicie sessão e leia o perfil do utilizador

      Esta é uma autorização predefinida que não deve ser removida. Quando removido, o OneDrive apresenta um erro a pedir-lhe que reponha esta autorização.

      Files.Read.All Aplicação Ler ficheiros em todas as coleções de sites

      Esta autorização permite que o Gemini Enterprise leia todos os ficheiros em todas as coleções de sites.

      Opções de controlo de sites
      Opção 1: Sites.FullControl.All Aplicação Controlo total sobre todos os sites

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em todos os sites do OneDrive.

      Se a concessão de controlo total sobre todos os sites lhe parecer excessiva, use a opção 2: Sites.Selected para conceder controlo detalhado.

      Opção 2: Sites.Selected Aplicação Controlo sobre os sites selecionados

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em sites do OneDrive selecionados. Esta autorização oferece um controlo mais detalhado em vez de Sites.FullControl.All

      Opções de leitura do perfil
      Opção 1: User.Read.All Aplicação Ler os perfis completos de todos os utilizadores Esta autorização permite que o Gemini Enterprise compreenda o controlo de acesso aos dados do seu conteúdo do OneDrive.
      Opção 2: User.ReadBasic.All Aplicação Ler os perfis básicos de todos os utilizadores Esta autorização permite que o Gemini Enterprise compreenda o controlo de acesso aos dados do seu conteúdo do OneDrive.
    2. Adicione e conceda as seguintes autorizações do OneDrive. Pode escolher entre Sites.FullControl.All e Sites.Selected:

      Autorizações do OneDrive para credenciais federadas

      Autorização Tipo Descrição Justificação
      Opção 1: Sites.FullControl.All Aplicação Controlo total sobre todos os sites

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em todos os sites do OneDrive.

      Se a concessão de controlo total sobre todos os sites lhe parecer excessiva, use a opção 2: Sites.Selected para conceder controlo detalhado.

      Opção 2: Sites.Selected Aplicação Controlo sobre os sites selecionados Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em sites do OneDrive selecionados.
    3. Para as autorizações adicionadas, verifique se a coluna Estado apresenta a autorização como Granted e tem um ícone de marca de verificação verde.

  5. Conceda o consentimento do administrador. Para obter informações sobre como conceder consentimento, consulte o artigo Conceda consentimento de administrador ao nível do inquilino a uma aplicação na documentação do Microsoft Entra.

Configure o OAuth 2.0 para o token de atualização e a concessão de palavra-passe

Pode usar o método OAuth 2.0 para configurar um registo de aplicação do Entra ID e ativar o acesso seguro ao OneDrive. Este método inclui passos para configurar o registo da app, conceder autorizações e estabelecer a autenticação.

Pode usar o seguinte processo para registar a aplicação no Entra ID com a autenticação OAuth 2.0 para o token de atualização e para a concessão de palavra-passe. Este método é preferível quando precisa de um controlo detalhado sobre as autorizações da API REST do OneDrive, o que lhe permite restringir o acesso aos recursos na conta de utilizador.

Algumas mensagens de erro comuns que pode encontrar durante este processo estão listadas em Mensagens de erro.

A tabela seguinte descreve as funções do OneDrive recomendadas para métodos de autenticação OAuth 2.0:

  1. Criar registo de app:

    1. Navegue para o centro de administração do ID do Entra.

    2. Crie um registo de app:

      • Tipos de contas suportados: apenas contas no diretório organizacional.
      • URI de redirecionamento: https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html.
    3. Anote o ID do cliente e o ID do inquilino.

  2. Adicione o segredo do cliente:

    1. Aceda a Certificados e segredos > Novo segredo do cliente.
    2. Anote a string secreta.
  3. Defina as autorizações da API.

    1. Adicione e conceda as seguintes autorizações do Microsoft Graph. Pode escolher entre Sites.FullControl.All e Sites.Selected:

      Autorizações do Microsoft Graph para autenticação OAuth 2.0

      Autorização Tipo Descrição Justificação
      GroupMember.Read.All Aplicação Ler todos os membros do grupo Esta autorização permite que o Gemini Enterprise compreenda as associações dos grupos de utilizadores no site do OneDrive.
      User.Read Delegada Inicie sessão e leia o perfil do utilizador

      Esta é uma autorização predefinida que não deve ser removida. Quando removido, o OneDrive apresenta um erro a pedir-lhe que reponha esta autorização.

      Opção 1: Sites.FullControl.All Aplicação Controlo total sobre todos os sites

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite ao Gemini Enterprise indexar documentos, eventos, comentários, anexos e ficheiros em todos os sites do OneDrive.

      Opção 2: Sites.Selected Aplicação Controlo sobre os sites selecionados

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em sites do OneDrive selecionados. Esta autorização oferece um controlo mais detalhado em vez de Sites.FullControl.All

      User.Read.All Aplicação Ler os perfis completos de todos os utilizadores Esta autorização permite que o Gemini Enterprise compreenda o controlo de acesso aos dados do seu conteúdo do OneDrive.
    2. Adicione e conceda as seguintes autorizações do OneDrive para autenticação OAuth 2.0. Pode escolher entre AllSites.FullControl e Sites.Selected:

      Autorizações do OneDrive para autenticação OAuth 2.0

      Autorização Tipo Descrição Justificação
      Opção 1: AllSites.FullControl Delegada Controlo total sobre todos os sites

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em todos os sites do OneDrive.

      Opção 2: Sites.Selected Delegada Controlo sobre os sites selecionados

      Esta autorização permite que o Gemini Enterprise obtenha os grupos de utilizadores e as atribuições de funções do OneDrive, que não estão incluídos na autorização Sites.Read.All. Também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e ficheiros em sites do OneDrive selecionados. Esta autorização oferece um controlo mais detalhado em vez de AllSites.FullControl.

    3. Para as autorizações adicionadas, verifique se a coluna Estado apresenta a autorização como Granted e tem um ícone de marca de verificação verde.

      Valide as autorizações da API
      Valide as autorizações da API

    4. Use uma conta de utilizador dedicada com acesso limitado a sites específicos. Verifique se esta conta tem acesso de proprietário aos sites selecionados.

  4. Conceda o consentimento do administrador. Para obter informações sobre como conceder consentimento, consulte o artigo Conceda consentimento de administrador ao nível do inquilino a uma aplicação na documentação do Microsoft Entra ID.

Mensagens de erro

A tabela seguinte descreve as mensagens de erro comuns e as respetivas descrições que pode encontrar quando associa o OneDrive ao Gemini Enterprise.

Código de erro Mensagem de erro
ONEDRIVE_MISSING_PERMISSION_1 Função da API REST obrigatória em falta (Sites.FullControl.All ou Sites.Selected). Para autorizações delegadas, faltam AllSites.FullControl ou Sites.Selected.
ONEDRIVE_MISSING_PERMISSION_2 Função da API Graph obrigatória em falta (Sites.FullControl.All ou Sites.Selected).
ONEDRIVE_MISSING_PERMISSION_3 Função da API Graph obrigatória GroupMember.Read.All em falta.
ONEDRIVE_MISSING_PERMISSION_4 Função da API Graph obrigatória em falta (User.Read.All ou User.ReadBasic.All).
ONEDRIVE_INVALID_SITE_URI Não foi possível obter o token de acesso da API Graph. Possíveis causas: ID de cliente, valor secreto ou credenciais federadas inválidas.
ONEDRIVE_INVALID_AUTH Não foi possível obter o token de acesso da API Graph. Possíveis causas: ID de cliente, valor secreto ou credenciais federadas inválidas.
ONEDRIVE_INVALID_JSON Falha ao analisar o conteúdo JSON.
ONEDRIVE_TOO_MANY_REQUESTS Foram enviados demasiados pedidos HTTP para o OneDrive; foi recebida uma resposta HTTP 429.
  1. Ficheiro de manifesto:

    1. Aceda ao separador Manifesto.
    2. Elimine o conteúdo entre [ e ] em requiredResourceAccess.

      manifest-file
      Edite o ficheiro de manifesto

    3. Cole o seguinte JSON entre os parênteses.

      {
       "resourceAppId": "00000003-0000-0000-c000-000000000000",
       "resourceAccess": [
         {
           "id": "01d4889c-1287-42c6-ac1f-5d1e02578ef6",
           "type": "Role"
         },
         {
           "id": "5b567255-7703-4780-807c-7be8301ae99b",
           "type": "Role"
         },
         {
           "id": "df021288-bdef-4463-88db-98f22de89214",
           "type": "Role"
         }
       ]
      }
      
    4. Regresse às autorizações da API.

    5. Confirme se todas as autorizações necessárias estão presentes.

    6. Conceda o consentimento do administrador.

Crie um conetor do OneDrive

Consola

Para usar a Google Cloud consola para sincronizar dados do OneDrive com o Gemini Enterprise, siga estes passos:

  1. Na Google Cloud consola, aceda à página Gemini Enterprise.

    Gemini Enterprise

  2. No menu de navegação, clique em Armazenamentos de dados.

  3. Clique em Criar arquivo de dados.

  4. Na página Selecione uma origem de dados, desloque a página ou pesquise OneDrive para associar a sua origem de terceiros.

  5. Em Definições de autenticação, selecione o método de autenticação a usar.

    1. Introduza as suas informações de autenticação.

    2. Clique em Continuar.

      onedrive-ingestion-auth-methods
      Selecione o método de autenticação e faculte as suas informações de autenticação.

  6. Selecione as seguintes entidades para sincronizar:

    • Ficheiro
  7. Para filtrar entidades do índice ou garantir que são incluídas no índice, clique em Filtrar.

    • fileName corresponde apenas ao nome do ficheiro.
    • filePath tem de ser um caminho completo da API Microsoft Graph, normalmente com o prefixo /drive/root:. Por exemplo, se o link direto do OneDrive for https:/example-my.onedrive.com/personal/user_example_com/Documents/folder1/folder2, então filePath é /drive/root:/folder1/folder2.

    onedrive-filters
    Especifique filtros para incluir ou excluir entidades

  8. Clique em Continuar.

  9. Selecione a Frequência de sincronização para a Sincronização completa e a Frequência de sincronização incremental para a Sincronização de dados incremental. Para mais informações, consulte o artigo Sincronize programações.

    Se quiser agendar sincronizações completas separadas de dados de entidades e identidades, expanda o menu em Sincronização completa e, de seguida, selecione Opções personalizadas.

    Opções personalizadas para a sincronização de dados completa.
    Definir agendas separadas para a sincronização completa de entidades e a sincronização completa de identidades.
  10. Selecione uma região para o seu repositório de dados.

  11. Introduza um nome para o arquivo de dados.

  12. Clique em Criar. O Gemini Enterprise cria o seu repositório de dados e apresenta os seus repositórios de dados na página Repositórios de dados.

  13. Para verificar o estado do carregamento, aceda à página Armazenamentos de dados e clique no nome do armazenamento de dados para ver os respetivos detalhes na página Dados. O estado do conector muda de A criar para Em execução quando começa a sincronizar dados. Quando o carregamento estiver concluído, o estado muda para Ativo para indicar que a ligação à sua origem de dados está configurada e a aguardar a próxima sincronização agendada.

    Consoante o tamanho dos seus dados, a carregamento pode demorar minutos ou horas.

Ative a sincronização em tempo real

Para ativar a sincronização em tempo real para o seu repositório de dados, siga estes passos.

  1. Na Google Cloud consola, aceda à página Gemini Enterprise.

    Gemini Enterprise

  2. No menu de navegação, clique em Armazenamentos de dados.

  3. Clique no nome do repositório de dados do OneDrive para o qual quer ativar a sincronização em tempo real.

  4. Na página Dados do arquivo de dados, aguarde até que o Estado do conetor mude para Ativo.

  5. No campo Sincronização em tempo real, clique em Ver/editar.

    Veja e edite as definições de sincronização em tempo real
    Veja e edite as definições de sincronização em tempo real.

  6. Clique no botão Ativar sincronização em tempo real para o ativar.

  7. Indique um valor para o segredo do cliente. Este valor é usado para validar os eventos do webhook do OneDrive. Recomendamos a utilização de uma string de 20 carateres.

    Ative a sincronização em tempo real e forneça um segredo do cliente
    Ative a sincronização em tempo real e forneça um segredo do cliente.

  8. Clique em Guardar.

    Aguarde até que o campo Sincronização em tempo real mude para Em execução.

Códigos de erro

A tabela seguinte lista os códigos de erro e as descrições do OneDrive.

Código de erro Descrição
ONEDRIVE_MISSING_PERMISSION_1 A aplicação não tem uma função Files.Read.All necessária para a API Graph.
ONEDRIVE_MISSING_PERMISSION_2 A aplicação não tem uma função Group.Read.All necessária para a API Graph.
ONEDRIVE_MISSING_PERMISSION_3 A aplicação não tem uma função User.Read.All obrigatória ou uma função User.ReadBasic.All para a API Graph.
ONEDRIVE_INVALID_SITE_URI O URL da instância é inválido.
ONEDRIVE_INVALID_AUTH Erro ao obter o token de acesso da API Graph. Isto pode dever-se a um ID do cliente, um valor secreto ou credenciais federadas inválidas em falta.
ONEDRIVE_UNCATEGORIZED_ERROR Não existe ou existe uma ACL inválida no ficheiro.
ONEDRIVE_TOO_MANY_REQUESTS São enviados demasiados pedidos HTTP para o OneDrive. Foi recebida uma resposta HTTP 429.

Passos seguintes

  • Para anexar o seu arquivo de dados a uma app, crie uma app e selecione o seu arquivo de dados seguindo os passos em Criar uma app.

  • Para pré-visualizar a apresentação dos resultados da pesquisa após a configuração da app e do arquivo de dados, consulte o artigo Pré-visualizar resultados da pesquisa.