Conectar o Microsoft OneDrive à ingestão de dados

Nesta página, descrevemos como conectar o Microsoft OneDrive ao Gemini Enterprise usando a ingestão de dados.

Use o procedimento a seguir para sincronizar dados do OneDrive.

Depois de configurar a fonte de dados e importar os dados pela primeira vez, o repositório de dados sincroniza as informações dessa fonte com uma frequência que você seleciona durante a configuração.

Limitações

A sincronização incremental não detecta ações no nível da pasta, como Copiar, Mover ou Renomear.

Antes de começar

Para aplicar o controle de acesso à fonte de dados e proteger os dados no Gemini Enterprise, verifique se você configurou seu provedor de identidade.

Sobre o registro de aplicativos do Microsoft Entra ID

Antes de criar o conector no Gemini Enterprise, é necessário configurar um registro de aplicativo do Microsoft Entra ID para ativar o acesso seguro ao OneDrive. A forma de registrar o aplicativo depende do método de autenticação selecionado ao criar o conector no Gemini Enterprise. Você pode escolher um dos seguintes métodos:

  • Credenciais federadas:

    • Permite que o Google acesse o OneDrive com segurança usando tokens assinados criptograficamente, evitando a necessidade de um usuário principal real.

    • É necessário um ID de assunto para registrar o Gemini Enterprise no Entra. Essa opção fica disponível quando você cria o conector do OneDrive no Gemini Enterprise.

    • Ao registrar seu app no Entra ID, você precisa 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.
      • Código do locatário
      • ID do cliente

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

    • O Google recomenda que você use esse método.

  • Token de atualização OAuth 2.0:

    • Oferece um controle granular sobre quem se conecta à API do OneDrive.

    • Ao registrar seu app no Entra ID, você precisa 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.
      • Código do locatário
      • ID do cliente
      • Chave secreta do cliente

      Esses 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 fazer login na sua conta do OneDrive.

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

    • Exige a criação de um novo usuário do OneDrive, o que pode aumentar os custos de licenciamento.

  • Concessão de senha do OAuth 2.0:

    • Oferece controle granular sobre quem se conecta à API do OneDrive.

    • Ao registrar seu app no Entra ID, você precisa 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.
      • Código do locatário
      • ID do cliente
      • Chave secreta do cliente

      Esses 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 fornecer o nome de usuário e a senha do Entra ID fornecidos pelo administrador.

    • Esse método é adequado quando a configuração do OneDrive não exige autenticação de dois fatores.

    • Esse método exige que você crie um novo usuário do OneDrive, o que pode adicionar custos de licenciamento.

Configurar credenciais federadas

Siga as etapas abaixo para configurar o registro do app, conceder permissões e estabelecer a autenticação. O Google recomenda usar o método de credenciais federadas.

Algumas mensagens de erro comuns que podem aparecer durante esse processo estão listadas em Mensagens de erro.

  1. Consiga o ID do cliente da conta de serviço:

    1. No console Google Cloud , acesse a página Gemini Enterprise.
    2. No menu de navegação, selecione Repositório de dados.
    3. Clique em Criar repositório de dados.
    4. Na página Selecionar uma fonte de dados, role a tela ou pesquise OneDrive para conectar sua fonte de terceiros.
    5. Anote o identificador do assunto. Não clique em Continuar ainda. Siga as próximas etapas desta tarefa e conclua as etapas no console do Google Cloud seguindo as instruções em Criar um conector do OneDrive.
  2. Registre o app no Entra ID:

    1. Acesse o centro de administração do Microsoft Entra.
    2. No menu, expanda a seção Aplicativos e selecione Registros de apps.
    3. Na página Registros de apps, selecione Novo registro.

      Registrar um novo app no Entra
      Registrar um novo app no centro de administração do Microsoft Entra

    4. Crie um registro de app na página Registrar um aplicativo:

      • Na seção Tipos de conta compatíveis, selecione Apenas contas no diretório organizacional.
      • Na seção URI de redirecionamento, selecione Web e insira o URI de redirecionamento https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html
      • Mantenha os valores padrão para as outras configurações e clique em Registrar.

      Registrar contas apenas no diretório organizacional
      Selecione o tipo de conta e insira o URI de redirecionamento

    5. Anote o ID do cliente e o ID do locatário.

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

  3. Adicione credenciais federadas:

    1. Acesse Certificados e chaves secretas > Credenciais federadas > Adicionar credencial.

      Adicionar credenciais federadas no Entra
      Adicionar credenciais federadas no Microsoft Entra

    2. Use as seguintes configurações:

      • Federated credential scenario: Other issuer

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

      • Identificador de assunto: use o valor de Identificador de assunto que você anotou na etapa anterior.

      • Nome: insira um nome exclusivo.

    3. Clique em Adicionar para conceder acesso.

      Conectar sua Conta do Google ao Microsoft Entra ID
      Conecte sua Conta do Google ao Microsoft Entra ID

  4. Defina as permissões da API.

    Selecione o app para definir permissões da API
    Selecione o app para definir as permissões da API

    1. Adicione e conceda as seguintes permissões do Microsoft Graph. Você pode escolher entre as opções de controle do site (Sites.FullControl.All e Sites.Selected) e as opções de leitura de perfil (User.Read.All e User.ReadBasic.All):

      Permissões do Microsoft Graph para credenciais federadas

      Permissão Tipo Descrição Motivo
      GroupMember.Read.All Aplicativo Ler todas as associações a grupos Com essa permissão, o Gemini Enterprise pode entender as associações dos grupos de usuários no site do OneDrive.
      User.Read Delegado Fazer login e ler o perfil do usuário

      Essa é uma permissão padrão que não pode ser removida. Quando removido, o OneDrive mostra um erro pedindo que você restabeleça essa permissão.

      Files.Read.All Aplicativo Ler arquivos em todas as coleções de sites

      Essa permissão permite que o Gemini Enterprise leia todos os arquivos em todas as coleções de sites.

      Opções de controle do site
      Opção 1: Sites.FullControl.All Aplicativo Controle total sobre todos os sites

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em todos os sites do OneDrive.

      Se conceder controle total sobre todos os sites parecer excessivo, use a opção 2: Sites.Selected para ter um controle granular.

      Opção 2: Sites.Selected Aplicativo Controle sobre os sites selecionados

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em sites selecionados do OneDrive. Essa permissão oferece um controle mais granular em vez de Sites.FullControl.All

      Opções de leitura de perfil
      Opção 1: User.Read.All Aplicativo Ler os perfis completos de todos os usuários Essa permissão permite que o Gemini Enterprise entenda o controle de acesso aos dados do seu conteúdo do OneDrive.
      Opção 2: User.ReadBasic.All Aplicativo Ler os perfis básicos de todos os usuários Essa permissão permite que o Gemini Enterprise entenda o controle de acesso aos dados do seu conteúdo do OneDrive.
    2. Adicione e conceda as seguintes permissões do OneDrive. Você pode escolher entre Sites.FullControl.All e Sites.Selected:

      Permissões do OneDrive para credenciais federadas

      Permissão Tipo Descrição Motivo
      Opção 1: Sites.FullControl.All Aplicativo Controle total sobre todos os sites

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em todos os sites do OneDrive.

      Se conceder controle total sobre todos os sites parecer excessivo, use a opção 2: Sites.Selected para ter um controle granular.

      Opção 2: Sites.Selected Aplicativo Controle sobre os sites selecionados Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em sites selecionados do OneDrive.
    3. Para as permissões adicionadas, verifique se a coluna Status lista a permissão como Granted e tem um ícone de marca de seleção verde.

  5. Conceda o consentimento do administrador. Para saber como conceder consentimento, consulte Conceder consentimento de administrador em todo o locatário a um aplicativo na documentação do Microsoft Entra.

Configurar o OAuth 2.0 para concessão de senha e token de atualização

Você pode usar o método OAuth 2.0 para configurar um registro de aplicativo do Entra ID e ativar o acesso seguro ao OneDrive. Esse método inclui etapas para configurar o registro do app, conceder permissões e estabelecer a autenticação.

Use o processo a seguir para registrar o aplicativo no Entra ID usando a autenticação OAuth 2.0 para token de atualização e concessão de senha. Esse método é preferível quando você precisa de controle granular sobre as permissões da API REST do OneDrive, permitindo restringir o acesso aos recursos na conta de usuário.

Algumas mensagens de erro comuns que podem aparecer durante esse processo estão listadas em Mensagens de erro.

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

  1. Crie um registro de app:

    1. Acesse o centro de administração do Entra ID.

    2. Crie um registro de app:

      • Tipos de conta compatíveis: 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 locatário.

  2. Adicione a chave secreta do cliente:

    1. Acesse Certificados e chaves secretas > Nova chave secreta do cliente.
    2. Anote a string do secret.
  3. Defina as permissões da API.

    1. Adicione e conceda as seguintes permissões do Microsoft Graph. Você pode escolher entre Sites.FullControl.All e Sites.Selected:

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

      Permissão Tipo Descrição Motivo
      GroupMember.Read.All Aplicativo Ler todas as associações a grupos Com essa permissão, o Gemini Enterprise pode entender as associações dos grupos de usuários no site do OneDrive.
      User.Read Delegado Fazer login e ler o perfil do usuário

      Essa é uma permissão padrão que não pode ser removida. Quando removido, o OneDrive mostra um erro pedindo que você restabeleça essa permissão.

      Opção 1: Sites.FullControl.All Aplicativo Controle total sobre todos os sites

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em todos os sites do OneDrive.

      Opção 2: Sites.Selected Aplicativo Controle sobre os sites selecionados

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em sites selecionados do OneDrive. Essa permissão oferece um controle mais granular em vez de Sites.FullControl.All

      User.Read.All Aplicativo Ler os perfis completos de todos os usuários Essa permissão permite que o Gemini Enterprise entenda o controle de acesso aos dados do seu conteúdo do OneDrive.
    2. Adicione e conceda as seguintes permissões do OneDrive para autenticação do OAuth 2.0. Você pode escolher entre AllSites.FullControl e Sites.Selected:

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

      Permissão Tipo Descrição Motivo
      Opção 1: AllSites.FullControl Delegado Controle total sobre todos os sites

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em todos os sites do OneDrive.

      Opção 2: Sites.Selected Delegado Controle sobre os sites selecionados

      Essa permissão permite que o Gemini Enterprise receba os grupos de usuários e as atribuições de função do OneDrive, que não estão incluídos na permissão Sites.Read.All. Ele também permite que o Gemini Enterprise indexe documentos, eventos, comentários, anexos e arquivos em sites selecionados do OneDrive. Essa permissão oferece um controle mais granular em vez de AllSites.FullControl.

    3. Para as permissões adicionadas, verifique se a coluna Status lista a permissão como Granted e tem um ícone de marca de seleção verde.

      Verificar as permissões da API
      Verifique as permissões da API

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

  4. Conceda o consentimento do administrador. Para saber como conceder consentimento, consulte Conceder consentimento de administrador em todo o locatário a um aplicativo na documentação do Microsoft Entra ID.

Mensagens de erro

A tabela a seguir descreve as mensagens de erro comuns e as descrições que podem aparecer ao conectar o OneDrive ao Gemini Enterprise.

Código do erro Mensagem de erro
ONEDRIVE_MISSING_PERMISSION_1 Função obrigatória da API REST ausente (Sites.FullControl.All ou Sites.Selected). Para permissões delegadas, AllSites.FullControl ou Sites.Selected estão ausentes.
ONEDRIVE_MISSING_PERMISSION_2 Função obrigatória da API Graph ausente (Sites.FullControl.All ou Sites.Selected).
ONEDRIVE_MISSING_PERMISSION_3 A função GroupMember.Read.All obrigatória da API Graph está faltando.
ONEDRIVE_MISSING_PERMISSION_4 Função obrigatória da API Graph ausente (User.Read.All ou User.ReadBasic.All).
ONEDRIVE_INVALID_SITE_URI Falha ao recuperar o token de acesso da API Graph. Possíveis causas: ID do cliente ou valor secreto inválido ou falta de credenciais federadas.
ONEDRIVE_INVALID_AUTH Falha ao recuperar o token de acesso da API Graph. Possíveis causas: ID do cliente ou valor secreto inválido ou falta de credenciais federadas.
ONEDRIVE_INVALID_JSON Não foi possível analisar o conteúdo JSON.
ONEDRIVE_TOO_MANY_REQUESTS Muitas solicitações HTTP enviadas ao OneDrive; recebida resposta HTTP 429.
  1. Arquivo de manifesto:

    1. Acesse a guia Manifesto.
    2. Exclua o conteúdo entre [ e ] em requiredResourceAccess.

      manifest-file
      Edite o arquivo de manifesto

    3. Cole o seguinte JSON entre os colchetes.

      {
       "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. Volte para as permissões da API.

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

    6. Conceda o consentimento do administrador.

Criar um conector do OneDrive

Console

Para usar o Google Cloud console e sincronizar dados do OneDrive com o Gemini Enterprise, siga estas etapas:

  1. No console Google Cloud , acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. No menu de navegação, selecione Repositório de dados.

  3. Clique em Criar repositório de dados.

  4. Na página Selecionar uma fonte de dados, role a tela ou pesquise OneDrive para conectar sua fonte de terceiros.

  5. Em Configurações de autenticação, selecione o método de autenticação que será usado.

    1. Insira suas informações de autenticação.

    2. Clique em Continuar.

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

  6. Selecione as seguintes entidades para sincronizar:

    • Arquivo
  7. Para filtrar entidades do índice ou garantir que elas sejam incluídas nele, clique em Filtrar.

    • fileName corresponde apenas ao nome do arquivo.
    • filePath precisa ser um caminho completo da API Microsoft Graph, geralmente 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
    Especificar filtros para incluir ou excluir entidades

  8. Clique em Continuar.

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

    Se quiser programar sincronizações completas separadas de dados de entidade e identidade, expanda o menu em Sincronização completa e selecione Opções personalizadas.

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

  11. Insira um nome para o repositório de dados.

  12. Clique em Criar. O Gemini Enterpriserise cria e exibe os repositórios de dados na página Repositórios de dados.

  13. Para verificar o status da ingestão, acesse a página Repositórios de dados e clique no nome do repositório de dados para conferir os detalhes na página Dados. O estado do conector muda de Criação para Execução quando ele começa a sincronizar dados. Quando a transferência for concluída, o estado vai mudar para Ativo para indicar que a conexão com a origem de dados está configurada e aguardando a próxima sincronização programada.

    Dependendo do tamanho dos dados, a ingestão pode levar minutos ou horas.

Ativar a sincronização em tempo real

Para ativar a sincronização em tempo real do repositório de dados, siga estas etapas.

  1. No console Google Cloud , acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. No menu de navegação, selecione Repositório de dados.

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

  4. Na página Dados do repositório de dados, aguarde até que o Estado do conector mude para Ativo.

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

    Ver e editar as configurações de sincronização em tempo real
    Ver e editar as configurações de sincronização em tempo real.

  6. Clique no botão Ativar sincronização em tempo real para a posição ativada.

  7. Informe um valor para Chave secreta do cliente. Esse valor é usado para verificar eventos de webhook do OneDrive. Recomendamos usar uma string de 20 caracteres.

    Ativar a sincronização em tempo real e fornecer uma chave secreta do cliente
    Ative a sincronização em tempo real e forneça uma chave secreta do cliente.

  8. Clique em Salvar.

    Aguarde o campo Sincronização em tempo real mudar para Em execução.

Códigos de erro

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

Código do erro Descrição
ONEDRIVE_MISSING_PERMISSION_1 O aplicativo não tem uma função Files.Read.All obrigatória para a API Graph.
ONEDRIVE_MISSING_PERMISSION_2 O aplicativo não tem uma função Group.Read.All necessária para a API Graph.
ONEDRIVE_MISSING_PERMISSION_3 O aplicativo não tem a função User.Read.All ou User.ReadBasic.All necessária para a API Graph.
ONEDRIVE_INVALID_SITE_URI O URL da instância é inválido.
ONEDRIVE_INVALID_AUTH Erro ao recuperar o token de acesso da API Graph. Isso pode acontecer devido a um ID do cliente ou valor secreto inválido ou à falta de credenciais federadas.
ONEDRIVE_UNCATEGORIZED_ERROR ACL inválida ou ausente no arquivo.
ONEDRIVE_TOO_MANY_REQUESTS Muitas solicitações HTTP são enviadas ao OneDrive. Recebeu resposta HTTP 429.

Próximas etapas

  • Para anexar seu repositório de dados a um app, crie um app e selecione o repositório seguindo as etapas em Criar um app.

  • Para ver como os resultados da pesquisa aparecem depois que o app e o repositório de dados são configurados, consulte Visualizar resultados da pesquisa.