Indexar dados de bibliotecas de documentos do SharePoint

Este artigo explica como configurar um indexador de pesquisa para indexar documentos armazenados em bibliotecas de documentos do SharePoint para pesquisa de texto completo no Azure AI Search. As etapas de configuração são as primeiras, seguidas por comportamentos e cenários

Caraterística

Um indexador no Azure AI Search é um rastreador que extrai dados pesquisáveis e metadados de uma fonte de dados. O indexador do SharePoint Online se conecta ao seu site do SharePoint e indexa documentos de uma ou mais bibliotecas de documentos. O indexador fornece a seguinte funcionalidade:

• Indexar arquivos e metadados de uma ou mais bibliotecas de documentos.
• Indexe incrementalmente, pegando apenas os arquivos e metadados novos e alterados.
• A deteção de exclusão é integrada. A exclusão em uma biblioteca de documentos é retomada na próxima execução do indexador e o documento é removido do índice.
• O texto e as imagens normalizadas são extraídos por padrão dos documentos indexados. Opcionalmente, você pode adicionar um conjunto de habilidades para um enriquecimento mais profundo da IA, como OCR ou tradução de texto.

Pré-requisitos

• SharePoint no serviço de nuvem Microsoft 365

• Ficheiros numa biblioteca de documentos

Formatos de documento suportados

O indexador do SharePoint Online pode extrair texto dos seguintes formatos de documento:

• CSV (consulte Indexação de blobs CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (consulte Indexação de blobs JSON)
• KML (XML para representações geográficas)
• Formatos do Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (e-mails do Outlook), XML (XML WORD de 2003 e 2006)
• Formatos de documentos abertos: ODT, ODS, ODP
• PDF
• Arquivos de texto sem formatação (consulte também Indexação de texto sem formatação)
• RTF
• XML
• CEP

Limitações e considerações

Aqui estão as limitações desse recurso:

• Não há suporte para indexação de Listas do SharePoint.

• Indexação do SharePoint . O conteúdo do site ASPX não é suportado.

• Não há suporte para arquivos de bloco de anotações do OneNote.

• O ponto de extremidade privado não é suportado.

• Renomear uma pasta do SharePoint não aciona a indexação incremental. Uma pasta renomeada é tratada como novo conteúdo.

• O SharePoint oferece suporte a um modelo de autorização granular que determina o acesso por usuário no nível do documento. O indexador não extrai essas permissões para o índice e o Azure AI Search não oferece suporte à autorização no nível do documento. Quando um documento é indexado do SharePoint em um serviço de pesquisa, o conteúdo fica disponível para qualquer pessoa que tenha acesso de leitura ao índice. Se você precisar de permissões no nível do documento, considere filtros de segurança para cortar os resultados e automatizar a cópia das permissões em um nível de arquivo para um campo no índice.

• Não há suporte para indexação de arquivos criptografados pelo usuário, arquivos protegidos por Gerenciamento de Direitos de Informação (IRM), arquivos ZIP com senhas ou conteúdo criptografado semelhante. Para que o conteúdo criptografado seja processado, o usuário com permissões adequadas para o arquivo específico deve remover a criptografia para que o item possa ser indexado de acordo quando o indexador executar a próxima iteração agendada.

• Não há suporte para indexação recursiva de subsites de um site específico fornecido.

• O indexador do SharePoint Online não é suportado quando o Acesso Condicional de ID do Microsoft ENTRA está habilitado.

Aqui estão as considerações ao usar esse recurso:

• Se você precisar criar um aplicativo Copilot / RAG (Retrieval Augmented Generation) personalizado para conversar com dados do SharePoint, a abordagem recomendada é usar o Microsoft Copilot Studio em vez desse recurso de visualização.

• Se você precisar de uma solução de indexação de conteúdo do SharePoint em um ambiente de produção, considere criar um conector personalizado com Webhooks do SharePoint, chamar a API do Microsoft Graph para exportar os dados para um contêiner de Blob do Azure e, em seguida, usar o indexador de blob do Azure para indexação incremental.

• Se sua configuração do SharePoint permitir que os processos do Microsoft 365 atualizem os metadados do sistema de arquivos do SharePoint, lembre-se de que essas atualizações podem acionar o indexador do SharePoint Online, fazendo com que o indexador ingira documentos várias vezes. Como o indexador do SharePoint Online é um conector de terceiros para o Azure, o indexador não pode ler a configuração ou variar seu comportamento. Ele responde a alterações em conteúdo novo e alterado, independentemente de como essas atualizações são feitas. Por esse motivo, certifique-se de testar sua configuração e entender a contagem de processamento de documentos antes de usar o indexador e qualquer enriquecimento de IA.

Configurar o indexador do SharePoint Online

Para configurar o indexador do SharePoint Online, use o portal do Azure e uma API REST de visualização. Você pode usar 2020-06-30-preview ou posterior. Recomendamos a API de visualização mais recente.

Esta seção fornece as etapas. Você também pode assistir ao vídeo a seguir.

Etapa 1 (opcional): Habilitar a identidade gerenciada atribuída ao sistema

Habilite uma identidade gerenciada atribuída ao sistema para detetar automaticamente o locatário no qual o serviço de pesquisa está provisionado.

Execute esta etapa se o site do SharePoint estiver no mesmo locatário que o serviço de pesquisa. Ignore esta etapa se o site do SharePoint estiver em um locatário diferente. A identidade não é usada para indexação, apenas deteção de locatário. Você também pode ignorar esta etapa se quiser colocar a ID do locatário na cadeia de conexão.

Depois de selecionar Salvar, você obtém uma ID de objeto que foi atribuída ao seu serviço de pesquisa.

Etapa 2: Decidir quais permissões o indexador requer

O indexador do SharePoint Online oferece suporte a permissões delegadas e de aplicativo . Escolha quais permissões você deseja usar com base no seu cenário.

Recomendamos permissões baseadas em aplicativos. Consulte as limitações para problemas conhecidos relacionados a permissões delegadas.

• Permissões de aplicativo (recomendado), onde o indexador é executado sob a identidade do locatário do SharePoint com acesso a todos os sites e arquivos. O indexador requer um segredo do cliente. O indexador também exigirá a aprovação do administrador do locatário antes de poder indexar qualquer conteúdo.

• Permissões delegadas, em que o indexador é executado sob a identidade do usuário ou aplicativo que envia a solicitação. O acesso aos dados é limitado aos sites e arquivos aos quais o chamador tem acesso. Para oferecer suporte a permissões delegadas, o indexador requer um prompt de código de dispositivo para entrar em nome do usuário. As permissões delegadas pelo usuário impõem a expiração do token a cada 75 minutos, de acordo com as bibliotecas de segurança mais recentes usadas para implementar esse tipo de autenticação. Este não é um comportamento que possa ser ajustado. Um token expirado requer indexação manual usando Run Indexer (visualização). Por esse motivo, você pode querer permissões baseadas em aplicativos.

Etapa 3: Criar um registro de aplicativo Microsoft Entra

O indexador do SharePoint Online usa esse aplicativo Microsoft Entra para autenticação.

1. Inicie sessão no portal do Azure.

2. Procure ou navegue até Microsoft Entra ID e, em seguida, selecione Registos de aplicações.

3. Selecione + Novo registo:

   1. Forneça um nome para seu aplicativo.
   2. Selecione Locatário único.
   3. Ignore a etapa de designação do URI. Nenhum URI de redirecionamento necessário.
   4. Selecione Registar.

4. À esquerda, selecione Permissões de API, Adicionar uma permissão e Microsoft Graph.

   • Se o indexador estiver usando permissões de API de aplicativo, selecione Permissões de aplicativo e adicione o seguinte:

     • Aplicação - Files.Read.All
     • Aplicação - Sites.Read.All

     

     Usar permissões de aplicativo significa que o indexador acessa o site do SharePoint em um contexto de serviço. Assim, quando você executar o indexador, ele terá acesso a todo o conteúdo no locatário do SharePoint, o que requer aprovação do administrador do locatário. Um segredo do cliente também é necessário para autenticação. A configuração do segredo do cliente é descrita mais adiante neste artigo.

   • Se o indexador estiver usando permissões de API delegadas, selecione Permissões delegadas e adicione o seguinte:

     • Delegado - Files.Read.All
     • Delegado - Sites.Read.All
     • Delegado - User.Read

     

     As permissões delegadas permitem que o cliente de pesquisa se conecte ao SharePoint sob a identidade de segurança do usuário atual.

5. Dê consentimento ao administrador.

   O consentimento do administrador do locatário é necessário ao usar permissões da API do aplicativo. Alguns locatários são bloqueados de tal forma que o consentimento do administrador do locatário também é necessário para permissões de API delegadas. Se qualquer uma dessas condições se aplicar, você precisará ter um administrador de locatário concedendo consentimento para este aplicativo Microsoft Entra antes de criar o indexador.

   

6. Selecione a guia Autenticação .

7. Defina Permitir fluxos de clientes públicos como Sim e selecione Salvar.

8. Selecione + Adicionar uma plataforma, depois Aplicações móveis e de ambiente de trabalho, depois selecione https://login.microsoftonline.com/common/oauth2/nativecliente, em seguida , Configurar.

   

9. (Somente permissões da API do aplicativo) Para autenticar no aplicativo Microsoft Entra usando permissões de aplicativo, o indexador requer um segredo do cliente.

   • Selecione Certificados & Segredos no menu à esquerda, depois Segredos do cliente e, em seguida, Novo segredo do cliente.

     

   • No menu que aparece, insira uma descrição para o novo segredo do cliente. Se necessário, ajuste a data de validade. Se o segredo expirar, ele precisa ser recriado e o indexador precisa ser atualizado com o novo segredo.

     

   • O novo segredo do cliente aparece na lista secreta. Depois de navegar para fora da página, o segredo não é mais estar visível, então copie-o usando o botão de cópia e salve-o em um local seguro.

     

Etapa 4: Criar fonte de dados

A partir desta seção, use uma API REST de visualização para as etapas restantes. Recomendamos a API de visualização mais recente.

Uma fonte de dados especifica quais dados indexar, credenciais e políticas para identificar com eficiência as alterações nos dados (linhas novas, modificadas ou excluídas). Uma fonte de dados pode ser usada por vários indexadores no mesmo serviço de pesquisa.

Para indexação do SharePoint, a fonte de dados deve ter as seguintes propriedades necessárias:

• name é o nome exclusivo da fonte de dados dentro do seu serviço de pesquisa.
• O tipo deve ser "sharepoint". Esse valor diferencia maiúsculas de minúsculas.
• as credenciais fornecem o ponto de extremidade do SharePoint e a ID do aplicativo (cliente) do Microsoft Entra. Um exemplo de ponto de extremidade do SharePoint é https://microsoft.sharepoint.com/teams/MySharePointSite. Você pode obter o ponto de extremidade navegando até a home page do seu site do SharePoint e copiando a URL do navegador.
• container especifica qual biblioteca de documentos indexar. As propriedades controlam quais documentos são indexados.

Para criar uma fonte de dados, chame Criar fonte de dados (visualização).

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "[connection-string]" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null }
}

Formato da cadeia de conexão

O formato da cadeia de conexão muda com base no fato de o indexador estar usando permissões de API delegadas ou permissões de API de aplicativo

• Formato de cadeia de conexão de permissões de API delegadas

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];TenantId=[SharePoint site tenant id]

• Formato de cadeia de conexão de permissões da API do aplicativo

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];ApplicationSecret=[Azure AD App client secret];TenantId=[SharePoint site tenant id]

Etapa 5: Criar um índice

O índice especifica os campos em um documento, atributos e outras construções que moldam a experiência de pesquisa.

Para criar um índice, chame Criar índice (visualização):

POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-index",
    "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "metadata_spo_item_name", "type": "Edm.String", "key": false, "searchable": true, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_path", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_content_type", "type": "Edm.String", "key": false, "searchable": false, "filterable": true, "sortable": false, "facetable": true },
        { "name": "metadata_spo_item_last_modified", "type": "Edm.DateTimeOffset", "key": false, "searchable": false, "filterable": false, "sortable": true, "facetable": false },
        { "name": "metadata_spo_item_size", "type": "Edm.Int64", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

Etapa 6: Criar um indexador

Um indexador conecta uma fonte de dados a um índice de pesquisa de destino e fornece uma programação para automatizar a atualização de dados. Depois que o índice e a fonte de dados forem criados, você poderá criar o indexador.

Se você estiver usando permissões delegadas, durante esta etapa, você será solicitado a entrar com credenciais da organização que têm acesso ao site do SharePoint. Se possível, recomendamos criar uma nova conta de usuário organizacional e dar a esse novo usuário as permissões exatas que você deseja que o indexador tenha.

Existem algumas etapas para criar o indexador:

1. Envie uma solicitação Criar indexador (visualização):

   POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
   Content-Type: application/json
   api-key: [admin key]
   
   {
       "name" : "sharepoint-indexer",
       "dataSourceName" : "sharepoint-datasource",
       "targetIndexName" : "sharepoint-index",
       "parameters": {
       "batchSize": null,
       "maxFailedItems": null,
       "maxFailedItemsPerBatch": null,
       "base64EncodeKeys": null,
       "configuration": {
           "indexedFileNameExtensions" : ".pdf, .docx",
           "excludedFileNameExtensions" : ".png, .jpg",
           "dataToExtract": "contentAndMetadata"
         }
       },
       "schedule" : { },
       "fieldMappings" : [
           { 
             "sourceFieldName" : "metadata_spo_site_library_item_id", 
             "targetFieldName" : "id", 
             "mappingFunction" : { 
               "name" : "base64Encode" 
             } 
            }
       ]
   }
   

   Se você estiver usando permissões de aplicativo, é necessário esperar até que a execução inicial seja concluída antes de começar a consultar seu índice. As instruções a seguir fornecidas nesta etapa referem-se especificamente a permissões delegadas e não são aplicáveis a permissões de aplicativos.

2. Quando você cria o indexador pela primeira vez, a solicitação Criar indexador (visualização) aguarda até que você conclua a próxima etapa. Você deve ligar para Obter status do indexador para obter o link e inserir o código do novo dispositivo.

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2024-05-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

   Se você não executar o Get Indexer Status dentro de 10 minutos, o código expirará e você precisará recriar a fonte de dados.

3. Copie o código de login do dispositivo da resposta Obter Status do Indexador. O login do dispositivo pode ser encontrado na "errorMessage".

   {
       "lastResult": {
           "status": "transientFailure",
           "errorMessage": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code <CODE> to authenticate."
       }
   }
   

4. Forneça o código que foi incluído na mensagem de erro.

   

5. O indexador do SharePoint Online acessará o conteúdo do SharePoint como o usuário conectado. O utilizador que inicia sessão durante este passo será o utilizador com sessão iniciada. Portanto, se você entrar com uma conta de usuário que não tenha acesso a um documento na Biblioteca de Documentos que deseja indexar, o indexador não terá acesso a esse documento.

   Se possível, recomendamos criar uma nova conta de usuário e dar a esse novo usuário as permissões exatas que você deseja que o indexador tenha.

6. Aprove as permissões que estão sendo solicitadas.

   

7. A solicitação inicial Criar Indexador (visualização) será concluída se todas as permissões fornecidas acima estiverem corretas e dentro do período de tempo de 10 minutos.

Etapa 7: Verificar o status do indexador

Depois que o indexador tiver sido criado, você poderá chamar Obter Status do Indexador:

GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]

Atualizando a fonte de dados

Se não houver atualizações para o objeto da fonte de dados, o indexador será executado em um agendamento sem qualquer interação do usuário.

No entanto, se você modificar o objeto da fonte de dados enquanto o código do dispositivo expirou, deverá entrar novamente para que o indexador seja executado. Por exemplo, se você alterar a consulta da fonte de dados, entre novamente usando o e obtenha o novo código do https://microsoft.com/devicelogin dispositivo.

Aqui estão as etapas para atualizar uma fonte de dados, assumindo um código de dispositivo expirado:

1. Chame o Indexador de Execução (visualização) para iniciar manualmente a execução do indexador.

   POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2024-05-01-preview  
   Content-Type: application/json
   api-key: [admin key]
   

2. Verifique o status do indexador.

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2024-05-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

3. Se você receber um erro solicitando a visita https://microsoft.com/devicelogin, abra a página e copie o novo código.

4. Cole o código na caixa de diálogo.

5. Execute manualmente o indexador novamente e verifique o status do indexador. Desta vez, a execução do indexador deve ser iniciada com êxito.

Indexação de metadados de documentos

Se você estiver indexando metadados de documentos ("dataToExtract": "contentAndMetadata"), os metadados a seguir estarão disponíveis para indexação.

O indexador do SharePoint Online também oferece suporte a metadados específicos para cada tipo de documento. Mais informações podem ser encontradas em Propriedades de metadados de conteúdo usadas na Pesquisa de IA do Azure.

Incluir ou excluir por tipo de ficheiro

Você pode controlar quais arquivos são indexados definindo critérios de inclusão e exclusão na seção "parâmetros" da definição do indexador.

Inclua extensões de arquivo específicas definindo "indexedFileNameExtensions" como uma lista separada por vírgulas de extensões de arquivo (com um ponto à esquerda). Exclua extensões de arquivo específicas definindo "excludedFileNameExtensions" as extensões que devem ser ignoradas. Se a mesma extensão estiver em ambas as listas, ela será excluída da indexação.

PUT /indexers/[indexer name]?api-version=2024-05-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

Controlando quais documentos são indexados

Um único indexador do SharePoint Online pode indexar conteúdo de uma ou mais bibliotecas de documentos. Use o parâmetro "container" na definição da fonte de dados para indicar quais sites e bibliotecas de documentos devem ser indexados.

A seção "container" da fonte de dados tem duas propriedades para essa tarefa: "name" e "query".

Nome

A propriedade "name" é necessária e deve ser um dos três valores:

Query

O parâmetro "query" da fonte de dados é composto por pares palavra-chave/valor. Abaixo estão as palavras-chave que podem ser usadas. Os valores são URLs de site ou URLs de biblioteca de documentos.

Processar erros

Por padrão, o indexador do SharePoint Online para assim que encontra um documento com um tipo de conteúdo sem suporte (por exemplo, uma imagem). Você pode usar o excludedFileNameExtensions parâmetro para ignorar determinados tipos de conteúdo. No entanto, talvez seja necessário indexar documentos sem conhecer todos os tipos de conteúdo possíveis com antecedência. Para continuar a indexação quando um tipo de conteúdo sem suporte for encontrado, defina o failOnUnsupportedContentType parâmetro de configuração como false:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    ... other parts of indexer definition
    "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}

Para alguns documentos, o Azure AI Search não consegue determinar o tipo de conteúdo ou não consegue processar um documento de outro tipo de conteúdo suportado. Para ignorar esse modo de falha, defina o failOnUnprocessableDocument parâmetro de configuração como false:

"parameters" : { "configuration" : { "failOnUnprocessableDocument" : false } }

O Azure AI Search limita o tamanho dos documentos indexados. Esses limites estão documentados em Limites de Serviço no Azure AI Search. Documentos superdimensionados são tratados como erros por padrão. No entanto, você ainda pode indexar metadados de armazenamento de documentos superdimensionados se definir indexStorageMetadataOnlyForOversizedDocuments o parâmetro de configuração como true:

"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }

Você também pode continuar a indexação se ocorrerem erros em qualquer ponto do processamento, seja durante a análise de documentos ou ao adicionar documentos a um índice. Para ignorar um número específico de erros, defina os maxFailedItems parâmetros e maxFailedItemsPerBatch de configuração para os valores desejados. Por exemplo:

{
    ... other parts of indexer definition
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}

Se um arquivo no site do SharePoint tiver a criptografia habilitada, uma mensagem de erro semelhante à seguinte poderá ser encontrada:

Code: resourceModified Message: The resource has changed since the caller last read it; usually an eTag mismatch Inner error: Code: irmEncryptFailedToFindProtector

A mensagem de erro também incluirá a ID do site do SharePoint, a ID da unidade e a ID do item da unidade no seguinte padrão: <sharepoint site id> :: <drive id> :: <drive item id>. Essas informações podem ser usadas para identificar qual item está falhando na extremidade do SharePoint. O usuário pode remover a criptografia do item para resolver o problema.

Consulte também

• Indexadores na Pesquisa de IA do Azure
• Propriedades de metadados de conteúdo usadas na Pesquisa de IA do Azure