Registrar e gerenciar o esquema dos conectores do Microsoft 365 Copilot

Este guia fornece diretrizes sobre como definir esquemas e seguir as práticas recomendadas para conectores do Microsoft 365 Copilot.

O esquema de conexão define como o conteúdo será usado nas experiências do Microsoft 365 Copilot. Um esquema é uma lista simples de todas as propriedades que você planeja adicionar à conexão. Cada propriedade inclui atributos, rótulos e aliases. Você deve registrar o esquema antes de adicionar itens à conexão.

A tabela a seguir mostra um esquema de exemplo para um conector do sistema de tíquete de trabalho:

Para obter referência de objeto de esquema e API, consulte a seção de esquema na referência da API do Copilot Connector.

Atributos do esquema

Esta seção descreve cada atributo de esquema e fornece as práticas recomendadas para usá-los.

Propriedade

Esse atributo refere-se ao nome da propriedade.

Práticas recomendadas:

• Use nomes claros e exclusivos – Certifique-se de que os nomes das propriedades sejam fáceis de entender e distinguir. Evite nomes ambíguos como orgName, brOrgName, ou tpOrgName. Em vez disso, use nomes descritivos, como parentOrganizationName ou departmentName para ajudar o Copilot a interpretar a propriedade corretamente.
• Evite nomes excessivamente técnicos ou enigmáticos – substitua nomes como dataBlob ou ftxInvIsLead por alternativas significativas como incidentRootCause ou qualifiedSalesLead para melhorar a legibilidade e a relevância para as consultas do usuário.
• Adicione descrições de propriedade – as descrições ajudam o Copilot a entender melhor e corresponder as propriedades às consultas do usuário.

Pesquisável

Quando uma propriedade é marcada como pesquisável, seu valor é adicionado ao índice de texto completo. Isso permite que o Copilot retorne resultados quando a consulta de um usuário corresponder à propriedade ou ao seu conteúdo.

Marque uma propriedade como pesquisável se:

• Ele contém dados textuais que os usuários provavelmente pesquisarão.
• É relevante para consultas de pesquisa (por exemplo, títulos, descrições, tags).
• Você deseja que ele contribua para as ocorrências de pesquisa e geração de snippets.

Exemplos comuns:title, description, tags, createdByassignedTo, .

Práticas recomendadas:

• Evite marcar campos binários grandes como pesquisáveis.
• Não marque campos refináveis como pesquisáveis — esses atributos são mutuamente exclusivos.
• Marque as propriedades como pesquisáveis apenas se elas forem essenciais para a relevância da pesquisa.

Uma pesquisa para design exibe os resultados de ocorrências em relação à propriedade (title) e ao conteúdo.

Consultável

Marque uma propriedade como consultável se os usuários precisarem filtrar seus resultados de pesquisa com base em valores específicos. Por exemplo, propriedades como ticketId, teamName, ou created podem ser consultáveis. Quando um usuário consulta algo como tickets created by William, o Copilot pode filtrar e retornar apenas os tíquetes relevantes. A correspondência de prefixo com operadores curinga (*) pode aumentar ainda mais a flexibilidade da pesquisa.

Marque uma propriedade como consultável se:

• É usado para filtrar ou restringir os resultados da pesquisa.
• Representa dados categóricos ou estruturados (por exemplo, status, prioridade, usuário atribuído).
• Você quer dar suporte a experiências de pesquisa personalizadas ou navegação facetada.

Exemplos comuns:

status (por exemplo, aberto, fechado), assignedTo (por exemplo, userEmail ou ID), priority (por exemplo, alto, médio, baixo) categoryou type.

Práticas recomendadas:

• Evite marcar campos de texto grandes (como descrições) como consultáveis.
• Combine Queryable: true com Retrievable: true para que a propriedade possa ser usada e mostrada nos resultados.
• Use Refinable: true se quiser que a propriedade apareça como um filtro na interface do usuário.

Neste exemplo, tags está marcado como consultável:

Uma pesquisa para tags:design reduzir o escopo dos resultados dos itens na designtags propriedade.

Se uma propriedade for consultável, você poderá consultá-la usando o KQL (QL por palavra-chave). O KQL dá suporte a palavras-chave de texto livre e restrições de propriedade. O nome da propriedade deve ser incluído na consulta, explícita ou programaticamente. A correspondência de prefixo com o operador curinga (*) é suportada.

Uma pesquisa para search ba\* exibir resultados que correspondam a este prefixo.

Recuperável

Marque uma propriedade como recuperável se seu valor for retornado nos resultados da pesquisa. Qualquer propriedade que apareça no modelo de exibição ou seja retornada de uma consulta deve ser recuperável. Seja seletivo — marcar propriedades muitas ou grandes como recuperáveis pode aumentar a latência da pesquisa.

Um conjunto de propriedades recuperáveis (title e lastEditedBy) renderizadas como resultado.

Marque uma propriedade como recuperável se:

• Você deseja que ele fique visível nos resultados da pesquisa.
• Ele fornece informações contextuais (por exemplo, título, status, usuário atribuído).

Exemplos comuns:
title, summary, description, status, assignedTo, createdDateTime.

Práticas recomendadas:

• Evite marcar campos confidenciais ou irrelevantes como recuperáveis.
• Use Retrievable: true para campos mostrados em cartões de pesquisa, prompts do Copilot ou interface do usuário personalizada.

Refinável

Marque uma propriedade como refinável se quiser que ela seja usada como um filtro em experiências de Pesquisa da Microsoft. As propriedades refináveis podem ser configuradas pelos administradores para aparecerem como filtros personalizados na página de resultados da pesquisa.

Quando uma propriedade é refinável:

• Ela pode ser usada para restringir os resultados da pesquisa.
• Ele aparece como um controle do refinador (por exemplo, lista suspensa ou caixa de seleção) na interface do usuário.
• Ele dá suporte à agregação em consultas de pesquisa.

Marque uma propriedade como refinável se:

• Representa dados categóricos ou estruturados.
• Você deseja que os usuários filtrem ou agrupem os resultados por esses valores.

Exemplos comuns:
tags (por exemplo, finanças, RH, engenharia), status (por exemplo, aberto, fechado, em andamento), priority (por exemplo, alto, médio, baixo), category, type.

Práticas recomendadas:

• Refinável e pesquisável são mutuamente exclusivos — uma propriedade não pode ser ambas.
• Somente tipos de cadeia de caracteres ou numéricos podem ser refinados.
• Marcar muitas propriedades como refináveis pode afetar o desempenho.

Refinar resultados por tags, uma propriedade refinável.

Correspondência exata necessária

Se isExactMatchRequired for definido como true para uma propriedade, o valor completo da cadeia de caracteres será indexado. Essa configuração só pode ser aplicada a propriedades que não são pesquisáveis.

Por exemplo, a ticketId propriedade é consultável e requer correspondência exata:

• A ticketId:CTS-ce913b61 consulta retorna o item com a ID do tíquete CTS-ce913b61.
• A consulta ticketId:CTSnão retorna o item com a ID do tíquete CTS-ce913b61.

Da mesma forma, a tags propriedade também usa correspondência exata:

• Consultar tags:contoso retorna itens com a marca contoso.
• Consultar tags:contosonão retorna itens com a tag contoso ticket.

Isso é especialmente útil quando a propriedade contém valores como GUIDs ou outros identificadores que devem ser correspondidos exatamente. Nesses casos, defina isExactMatchRequired como true.

Se isExactMatchRequired não for especificado, o padrão é .false Por exemplo, a title propriedade não requer correspondência exata. Ele é indexado com base nas regras de idioma do conteúdo do item:

• Consultar title: Contoso Title retorna itens que contêm um ou ContosoTitle no título.

Rótulos semânticos

Um rótulo semântico é uma marca conhecida publicada pela Microsoft que você pode atribuir a uma propriedade em seu esquema. Ao criar um conector Copilot personalizado usando a API do Graph, é essencial aplicar rótulos semânticos. Esses rótulos ajudam o Microsoft 365 Copilot e a Pesquisa da Microsoft a entender o significado e a função de cada propriedade, melhorando a pesquisa, o resumo e a experiência geral do usuário.

Você pode atribuir rótulos semânticos usando a API do Graph ou na página Atribuir rótulos de propriedade ao usar o SDK. Os rótulos fornecem significado semântico e permitem que os dados do conector se integrem perfeitamente às experiências do Microsoft 365.

Por exemplo, diferentes ferramentas de gerenciamento de projetos (como JIRA, Azure DevOps, Asana) podem usar termos diferentes para o usuário que criou um item de trabalho, como owner, ownedBy, ou assignedTo. Se sua propriedade servir a uma finalidade semelhante, você poderá atribuir o createdBy rótulo semântico.

Você pode atribuir rótulos semânticos às propriedades de origem usando a API do graph ou na página Atribuir rótulos de propriedade ao usar o SDK. Os rótulos fornecem significado semântico e permitem que você integre os dados do conector às experiências do Microsoft 365.

Práticas recomendadas:

• Adicione quantos rótulos forem relevantes, mas certifique-se de que eles sejam mapeados com precisão.
• Não atribua um rótulo a uma propriedade se ele não corresponder à sua finalidade — mapeamentos incorretos degradam a experiência.

O title rótulo é o mais importante. A atribuição de uma propriedade a esse rótulo permite que sua conexão participe da experiência do cluster de resultados. Embora nem todos os rótulos precisem ser usados, certifique-se de que os que você atribui sejam significativos e precisos.

Relevância

A aplicação de rótulos semânticos mapeados com precisão melhora a descoberta do conteúdo por meio da pesquisa. A Microsoft recomenda definir o maior número possível dos seguintes rótulos, listados em ordem decrescente de seu impacto na descoberta:
title, lastModifiedDateTime, lastModifiedBy, url, fileName e fileExtension.

Certifique-se de que os mapeamentos de etiquetas sejam precisos. Atribuir um rótulo a uma propriedade que contém conteúdo grande pode aumentar a latência da pesquisa e atrasar os resultados.

Dicas de classificação

As dicas de classificação podem ser aplicadas a propriedades textuais que:

• São pesquisáveis
• Não são mapeados para rótulos semânticos

As dicas de classificação ajudam a priorizar determinadas propriedades nos resultados da pesquisa. Você pode definir sua importância de padrão para muito alta no portal de administração do Microsoft 365 Search. Essas dicas são usadas junto com outros atributos de item para retornar os resultados mais relevantes.

Para configurar dicas de classificação:

1. Acesse a guia Pesquisa e inteligência no portal de administração do Microsoft 365.
2. SelecioneAjuste de relevância depersonalização>.

3. Em Ajuste de relevância, escolha Exibir detalhes>Configurar dicas de classificação.

4. Altere os pesos de importância nas propriedades de origem disponíveis.

Tipos de resultado padrão

Os rótulos semânticos também influenciam como os tipos de resultados padrão são gerados. No mínimo, atribuir os title rótulos and content garante que um tipo de resultado seja criado para sua conexão.

Um tipo de resultado padrão com title e um trecho de resultado.

Para aprimorar a experiência de resultado padrão, defina os seguintes rótulos quando aplicável (listados em ordem crescente de impacto):
title, url, lastModifiedBy, lastModifiedDateTime, fileName e fileExtension.

Lista de verificação de validação para atribuição de rótulos:

• As propriedades atribuídas a rótulos devem ser marcadas como recuperáveis.
• O tipo de dados da propriedade deve corresponder ao tipo esperado para o rótulo.
• Cada rótulo deve ser mapeado para exatamente uma propriedade.

Aliases

Aliases são nomes amigáveis atribuídos a propriedades. Eles são usados em consultas e em filtros de propriedades refináveis para melhorar a usabilidade e a flexibilidade de consulta.

Aqui estão alguns exemplos do mundo real:

Práticas recomendadas para aliases:

• Use aliases para sinônimos comuns ou termos específicos do domínio.
• Evite aliases excessivamente genéricos ou ambíguos.
• Mantenha os aliases curtos e intuitivos.

Propriedade de conteúdo

O esquema do conector do Microsoft Copilot dá suporte a uma propriedade padrão chamada content. Você não precisa defini-lo no esquema como outras propriedades (por exemplo, título, tags, etc.). Em vez disso, ele é incluído diretamente no conteúdo do item quando você ingere dados.

O esquema do content conector do Microsoft Copilot inclui uma propriedade interna. Ao contrário de outras propriedades (como title ou tags), você não precisa defini-lo no esquema. Em vez disso, ele é incluído diretamente no conteúdo do item durante a ingestão de dados.

A content propriedade é:

• Indexado semanticamente para pesquisa de texto.
• Usado para gerar snippets dinâmicos nos resultados da pesquisa.
• Disponível para o Copilot para resumo e compreensão semântica.

Práticas recomendadas para usar a propriedade content:

• Adicione todos os dados não estruturados à propriedade para permitir que o Copilot execute pesquisas semânticas content e corresponda as consultas com eficiência.
• Para conteúdo não estruturado ou de forma livre, inclua propriedades como summary, comment, rootCause, e description no content campo.
• Mantenha essas propriedades como campos recuperáveis separados somente se o valor total precisar ser exibido na interface do usuário.
• Você pode acrescentar várias propriedades (por exemplo, summary, description) ao campo para enriquecer a content compreensão semântica.

Um exemplo de como a propriedade é usada durante a content ingestão de dados:

{ 
"@odata.type": "microsoft.graph.externalItem", 
"acl": [ 
{ 
"type": "everyone", 
"value": "everyone", 
"accessType": "grant" 
} 
], 

"properties": { 
"title": "Payment Gateway Error", 
"priority": "High", 
"assignee": "john.doe@contoso.com" 
}, 

"content": { 
"value": "Rootcause : Error in payment gateway : MoreDetails about the error.......", 
"type": "text" 
} 
}

Agentes declarativos e descrições de propriedades

Se você estiver usando um agente declarativo (DA), deverá incluir descrições de propriedade do esquema do conector do Copilot no conjunto de instruções fornecido ao agente. Isso ajuda o promotor a entender:

• O significado semântico de cada propriedade
• Como referenciar e resumir os dados
• Como responder às consultas dos usuários usando o conteúdo indexado

Defina descrições claras e bem formadas para todas as propriedades. Uma boa descrição deve explicar:

• O que a propriedade representa
• Quaisquer nomes ou termos alternativos
• Quando e como deve ser usado

Recursos de atualização de esquema

Esta seção descreve os recursos de atualização da API de esquema .

Adicionar uma propriedade

Você pode adicionar uma nova propriedade ao seu esquema. Embora a reingestão não seja necessária, ela é recomendada. Ao adicionar uma propriedade, inclua todos os atributos de pesquisa necessários.

Adicionar ou remover um recurso de pesquisa

Você pode modificar os atributos de pesquisa de uma propriedade. No entanto:

• Você não pode adicionar um atributo refinável como parte de uma atualização de esquema.
• Uma propriedade não pode ser pesquisada e refinável.

Adicionar ou remover um recurso de pesquisa requer reingestão.

Adicionar ou remover um alias

Você pode adicionar ou remover aliases para uso em consultas de pesquisa. No entanto, os aliases que foram criados automaticamente pelo sistema para propriedades refináveis não podem ser removidos.

Adicionar ou remover um rótulo semântico

Você pode atribuir ou remover rótulos semânticos. Esses rótulos influenciam experiências como Relevância e Viva Topics.

Próximas etapas

• Adicionar itens à conexão
• Revisar a referência da API de conectores do Copilot
• Pesquisar tipos personalizados (externalItem)