Indexar dados de bibliotecas de documentos do SharePoint

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

Funcionalidade

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

• Indexe os arquivos e metadados de uma ou mais bibliotecas de documentos.
• Indexe de maneira incremental, pegando apenas os arquivos e metadados novos e alterados.
• A detecção de exclusão é criada. A exclusão em uma biblioteca de documentos é detectada na próxima execução do indexador e o documento é removido do índice.
• Imagens de texto e normalizadas serão extraídas, por padrão, dos documentos que são indexados. Opcionalmente, você pode adicionar um conjunto de habilidades para enriquecimento de IA mais profundo, como OCR ou tradução de texto.

Pré-requisitos

• Serviço de nuvem SharePoint no Microsoft 365

• Arquivos em uma biblioteca de documentos

Formatos de documento com suporte

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

• CSV (consulte Indexando BLOBs CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (consulte Como indexar blobs JSON)
• KML (XML para representações geográficas)
• Formatos do Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (emails do Outlook) e XML (WORD XML 2003 e 2006)
• Abrir formatos de documento: ODT, ODS, ODP
• PDF
• Arquivos de texto sem formatação (consulte também Como indexar texto sem formatação)
• RTF
• XML
• ZIP

Limitações e considerações

Estas são as limitações desse recurso:

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

• Não há suporte para indexação do conteúdo do site .ASPX do SharePoint.

• Não há suporte para arquivos de notebook do OneNote.

• Não há suporte para ponto de extremidade privado.

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

• O SharePoint dá suporte a um modelo de autorização granular que determina o acesso por usuário no nível do documento. O indexador não efetua pull dessas permissões no índice de pesquisa e a Pesquisa de IA do Azure não dá 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 pelo IRM (Information Rights Management), 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 precisa 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 de subsites recursivamente de um site específico fornecido.

• O indexador do SharePoint Online não tem suporte quando o Acesso Condicional do Microsoft ENTRA ID está habilitado.

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

• Se você precisar criar um aplicativo Copilot / RAG (Geração Aumentada por Recuperação) personalizado para conversar com dados do SharePoint, a abordagem recomendada é usar o Microsoft Copilot Studio em vez dessa versão prévia do recurso.

• 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 SharePoint Webhooks, chamando Microsoft Graph API para exportar os dados para um contêiner de Blob do Azure e, em seguida, use o Indexador de blob do Azure para indexação incremental.

• Se a sua configuração do SharePoint permitir que os processos do Microsoft 365 atualizem os metadados do sistema de arquivos do SharePoint, esteja ciente 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 consegue ler a configuração nem variar o seu comportamento. Ele responde a alterações no conteúdo novo e alterado, independentemente de como essas atualizações são feitas. Por esse motivo, você deve testar a 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, utilize o portal do Azure e uma API REST de pré-visualização. Você pode usar a 2020-06-30-preview ou posterior. Recomendamos a API de versão prévia mais recente.

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

Etapa 1 (opcional): habilitar identidade gerenciada atribuída pelo sistema

Habilite uma identidade gerenciada atribuída pelo sistema para detectar automaticamente o locatário no qual o serviço de pesquisa é provisionado.

Execute esta etapa se o site do SharePoint estiver no mesmo locatário que o serviço de pesquisa. Ignore-a se o site do SharePoint estiver em um locatário diferente. A identidade não é usada para indexação, apenas detecçã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ê verá uma ID do objeto que foi atribuída ao seu serviço de pesquisa.

Etapa 2: decidir que 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 aplicativo. Consulte limitações para problemas conhecidos relacionados a permissões delegadas.

• Permissões de aplicativo (recomendado), nas quais 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á aprovação do administrador de locatários para poder indexar qualquer conteúdo.

• Permissões delegadas, em que o indexador é executado sob a identidade do usuário ou do aplicativo que envia a solicitação. O acesso a dados é limitado aos sites e arquivos aos quais o chamador tem acesso. Para dar suporte a permissões delegadas, o indexador exige 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. Esse não é um comportamento que pode ser ajustado. Um token expirado requer indexação manual usando Executar Indexador (versão prévia). Por esse motivo, talvez você queira permissões baseadas em aplicativo.

Etapa 3: criar um registro de aplicativo do Microsoft Entra

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

1. Entre no portal do Azure.

2. Pesquise ou navegue até o Microsoft Entra ID, selecione Registros de aplicativo.

3. Selecione + Novo Registro:

   1. Insira um nome para seu aplicativo.
   2. Selecione Único locatário.
   3. Ignore a etapa de designação de URI. Nenhuma URI de redirecionamento necessária.
   4. Selecione Registrar.

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

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

     • Aplicativo - Files.Read.All
     • Aplicativo - Sites.Read.All

     

     O uso de permissões de aplicativo significa que o indexador acessará o site do SharePoint no contexto do usuário. Portanto, 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 de locatários. Um segredo do cliente também é necessário para autenticação. A configuração do segredo do cliente é descrita posteriormente neste artigo.

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

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

     

     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ê o consentimento do administrador.

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

   

6. Selecione a guia Autenticação.

7. Defina Permitir fluxos de cliente público como Sim e, em seguida, selecione Salvar.

8. Selecione + Adicionar uma plataforma, em seguida, Aplicativos móveis e de área de trabalho, em seguida, verificação https://login.microsoftonline.com/common/oauth2/nativeclient e, em seguida, Configurar.

   

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

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

     

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

     

   • O novo segredo do cliente aparecerá na lista de segredos. Depois que você sair da página, o segredo não ficará mais visível, portanto, copie-o usando o botão copiar e salve-o em um local seguro.

     

Etapa 4: criar uma fonte de dados

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

Uma fonte de dados especifica quais dados indexar, as credenciais e as políticas que identificam 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 a indexação do SharePoint, a fonte de dados deve ter as seguintes propriedades obrigatórias:

• name é o nome exclusivo da fonte de dados dentro de seu serviço de pesquisa.
• 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 do Microsoft Entra (cliente). Um exemplo de ponto de extremidade do SharePoint é https://microsoft.sharepoint.com/teams/MySharePointSite. Você pode obter o ponto de extremidade navegando até a página inicial do site do SharePoint e copiando a URL do navegador.
• contêiner especifica qual biblioteca de documentos a indexar. As propriedades controlam quais documentos são indexados.

Para criar uma fonte de dados, chame Criar Fonte de Dados (versão prévia).

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 se o indexador estiver usando permissões delegadas de API ou permissões de aplicativo de API

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

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

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

  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 modelam a experiência de pesquisa.

Para criar um índice, chame Criar Índice (versão prévia):

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 um agendamento para automatizar a atualização de dados. Após o índice e a fonte de dados terem sido criados, você poderá criar o indexador.

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

Há algumas etapas para criar o indexador:

1. Envie uma solicitação de Criar indexador (versão prévia):

   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 as permissões do aplicativo, será necessário aguardar até que a execução inicial seja concluída antes de começar a consultar o índice. As instruções a seguir fornecidas nesta etapa pertencem especificamente às permissões delegadas e não são aplicáveis às permissões do aplicativo.

2. Ao criar o indexador pela primeira vez, a solicitação Criar indexador (versão prévia) aguarda até que a próxima etapa seja concluída. Você deve chamar Obter Status do Indexador para obter o link e inserir o novo código do 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 Obter Status do Indexador dentro de dez minutos, o código expirará e você precisará recriar a fonte de dados.

3. Copie o código de logon do dispositivo da resposta Obter Status do Indexador. O logon 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 usuário conectado. O usuário que faz logon durante esta etapa será o usuário conectado. 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, é recomendável criar uma nova conta de usuário e dar a esse novo usuário as permissões exatas que deseja que o indexador tenha.

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

   

7. A solicitação inicial Criar Indexador (versão prévia) será concluída se todas as permissões fornecidas acima estiverem corretas e dentro do período de dez 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]

Atualização da fonte de dados

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

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

Estas são as etapas para atualizar uma fonte de dados, supondo que você tenha um código de dispositivo expirado:

1. Chame Executar Indexador (versão prévia) 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 que você visite 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 sucesso.

Indexar metadados de documento

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

O indexador do SharePoint Online também dá suporte a metadados específicos para cada tipo de documento. Veja mais em Propriedades de metadados de conteúdo usadas no Azure AI Search.

Incluir ou excluir por tipo de arquivo

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 as extensões de arquivo específicas definindo "excludedFileNameExtensions" nas extensões que devem ser ignoradas. Se a mesma extensão estiver nas duas 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" 
        } 
    }
}

Controlar 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 de quais sites e bibliotecas de documentos indexar.

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

Nome

A propriedade "name" é exigida e precisa ter um destes três valores:

Query

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

Tratar erros

Por padrão, o indexador do SharePoint Online é interrompido assim que encontra um documento com um tipo de conteúdo sem suporte (por exemplo, uma imagem). É possível usar o parâmetro excludedFileNameExtensions para ignorar alguns tipos de conteúdo. No entanto, talvez você precise indexar documentos sem conhecer todos os possíveis tipos de conteúdo com antecedência. Para continuar a indexação quando um tipo de conteúdo sem suporte é encontrado, defina o failOnUnsupportedContentType parâmetro de configuração como falso:

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 é capaz de determinar o tipo de conteúdo ou não é capaz de processar um documento com tipo de conteúdo compatível. Para ignorar este modo de falha, defina o parâmetro de configuração failOnUnprocessableDocument como false:

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

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

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

Também é possível continuar a indexação se ocorrem erros a qualquer momento do processamento, ao analisar documentos ou ao adicionar documentos a um índice. Para ignorar um número específico de erros, defina os parâmetros de configuração maxFailedItems e maxFailedItemsPerBatch como 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 de 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. Em seguida, o usuário pode remover a criptografia do item para resolver o problema.

Confira também

• Indexadores no Azure AI Search
• Propriedades de metadados de conteúdo usadas no Azure AI Search