Registar e gerir o esquema dos conectores Microsoft 365 Copilot

Este guia fornece orientações sobre como definir esquemas e seguir as melhores práticas para conectores Microsoft 365 Copilot.

O esquema de ligação define a forma como os seus conteúdos são utilizados nas experiências de Microsoft 365 Copilot. Um esquema é uma lista simples de todas as propriedades que planeia adicionar à ligação. Cada propriedade inclui atributos, etiquetas e aliases. Tem de registar o esquema antes de adicionar itens à ligação.

A tabela seguinte mostra um esquema de exemplo para um conector do sistema de pedidos de trabalho:

Propriedade	Tipo	Pesquisável	Consultável	Recuperável	Refinável	Correspondência exata necessária	Rótulos	Aliases
ticketId	Cadeia de caracteres		✔️			✔️		ID
title	Cadeia de caracteres	✔️	✔️	✔️			Título
createdBy	Cadeia de caracteres	✔️	✔️				createdBy	criador
assignedTo	Cadeia de caracteres	✔️	✔️
lastEditedDate	DateTime		✔️	✔️	✔️		lastModifiedDateTime	editedDate
lastEditedBy	Cadeia de caracteres	✔️	✔️	✔️			lastModifiedBy	editado
workItemType	Cadeia de caracteres		✔️	✔️				ticketType
prioridade	Int64	✔️
categorias	StringCollection		✔️	✔️	✔️	✔️
status	Cadeia de caracteres		✔️	✔️
url	Cadeia de caracteres						url
resolvido	Booliano		✔️	✔️

Para referência do objeto de esquema e da API, veja a secção de esquema na referência da API do Conector Copilot.

Atributos de esquema

Esta secção descreve cada atributo de esquema e fornece as melhores práticas para utilizá-los.

Propriedade

Este atributo refere-se ao nome da propriedade .

Práticas recomendadas:

• Utilizar nomes claros e exclusivos – certifique-se de que os nomes das propriedades são fáceis de compreender e distinguir. Evite nomes ambíguos como orgName, brOrgNameou tpOrgName. Em vez disso, utilize nomes descritivos, como parentOrganizationName ou departmentName para ajudar Copilot a interpretar a propriedade corretamente.
• Evitar 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 das consultas dos utilizadores.
• Adicionar descrições de propriedades – as descrições ajudam o Copilot a compreender melhor e a corresponder as propriedades às consultas do utilizador.

Observação

O suporte para adicionar descrições de propriedades a conectores personalizados é esperado no 4.º trimestre de 2025.
Ao utilizar agentes declarativos (DA), inclua descrições de propriedades no conjunto de instruções do DA.

Pesquisável

Quando uma propriedade é marcada como pesquisável, o respetivo valor é adicionado ao índice de texto completo. Isto permite que o Copilot devolva resultados quando a consulta de um utilizador corresponde à propriedade ou ao respetivo conteúdo.

Marcar uma propriedade como pesquisável se:

• Contém dados textuais que é provável que os utilizadores procurem.
• É relevante para consultas de pesquisa (por exemplo, títulos, descrições, etiquetas).
• Quer que contribua para a geração de resultados e fragmentos de pesquisa.

Exemplos comuns:title, description, , createdBytags, assignedTo.

Práticas recomendadas:

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

Uma pesquisa de design apresenta resultados de resultados na propriedade (title) e no conteúdo.

Consultável

Marque uma propriedade como queryable se os utilizadores precisarem de filtrar os resultados da pesquisa com base em valores específicos. Por exemplo, propriedades como ticketId, teamNameou created podem ser consultados. Quando um utilizador consulta algo como tickets created by William, o Copilot pode filtrar e devolver apenas as permissões relevantes. A correspondência de prefixos com operadores de carateres universais (*) pode melhorar ainda mais a flexibilidade de pesquisa.

Marcar uma propriedade como queryable se:

• É utilizado para filtrar ou reduzir os resultados da pesquisa.
• Representa dados categóricos ou estruturados (por exemplo, status, prioridade, utilizador atribuído).
• Quer suportar experiências de pesquisa personalizadas ou navegação por facetas.

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 consulta.
• Combine Queryable: true com Retrievable: true para que a propriedade possa ser utilizada e apresentada nos resultados.
• Utilize Refinable: true se quiser que a propriedade apareça como um filtro na IU.

Neste exemplo, tags está marcado como queryable:

Uma pesquisa para analisar tags:design os resultados para itens com design na tags propriedade .

Se uma propriedade for consultada, pode consultar a mesma através de KQL (Linguagem de Consulta de Palavra-chave). A KQL suporta palavras-chave de texto livre e restrições de propriedades. O nome da propriedade tem de ser incluído na consulta, seja explicitamente ou através de programação. A correspondência de prefixos com o operador de caráter universal (*) é suportada.

Observação

Não há suporte para correspondência de sufixo.

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

Recuperável

Marcar uma propriedade como recuperável se o respetivo valor deve ser devolvido nos resultados da pesquisa. Qualquer propriedade que apareça no modelo de apresentação ou seja devolvida a partir de uma consulta tem de ser recuperável. Seja seletivo— marcar demasiadas ou grandes propriedades como recuperáveis pode aumentar a latência da pesquisa.

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

Marcar uma propriedade como recuperável se:

• Quer que fique visível nos resultados da pesquisa.
• Fornece informações contextuais (por exemplo, título, status, utilizador atribuído).

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

Práticas recomendadas:

• Evite marcar campos confidenciais ou irrelevantes como recuperáveis.
• Utilize Retrievable: true para campos apresentados em cartões de pesquisa, pedidos copiadores ou IU personalizada.

Refinável

Marque uma propriedade como refinável se quiser que seja utilizada como um filtro nas experiências do Microsoft Search. 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:

• Pode ser utilizado para restringir os resultados da pesquisa.
• Aparece como um controlo de refinador (por exemplo, lista pendente ou caixa de verificação) na IU.
• Suporta a agregação em consultas de pesquisa.

Marcar uma propriedade como refinável se:

• Representa dados categóricos ou estruturados.
• Pretende que os utilizadores filtrem ou agrupem os resultados por estes valores.

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

Práticas recomendadas:

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

Refine os resultados por tags, uma propriedade refinável.

Correspondência exata necessária

Se isExactMatchRequired estiver definido como true para uma propriedade, o valor de cadeia completo é indexado. Esta definição só pode ser aplicada a propriedades que não são pesquisáveis.

Por exemplo, a ticketId propriedade é consultada e requer correspondência exata:

• A consulta ticketId:CTS-ce913b61 devolve o item com o ID da permissão CTS-ce913b61.
• A consulta ticketId:CTSnão devolve o item com o ID do pedido CTS-ce913b61.

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

• A consulta tags:contoso devolve itens com a etiqueta contoso.
• A consulta tags:contosonão devolve itens com a etiqueta contoso ticket.

Isto é especialmente útil quando a propriedade contém valores como GUIDs ou outros identificadores que têm de ser exatamente correspondidos. Nestes casos, defina isExactMatchRequired como true.

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

• A consulta title: Contoso Title devolve itens que contêm ou ContosoTitle no título.

Rótulos semânticos

Uma etiqueta semântica é uma etiqueta bem conhecida publicada pela Microsoft que pode atribuir a uma propriedade no seu esquema. Ao criar um conector Copilot personalizado com o microsoft API do Graph, a aplicação de etiquetas semânticas é essencial. Estas etiquetas ajudam a Microsoft 365 Copilot e o Microsoft Search a compreender o significado e a função de cada propriedade, melhorando a pesquisa, o resumo e a experiência geral do utilizador.

Pode atribuir etiquetas semânticas com o API do Graph ou a partir da página Atribuir etiquetas de propriedades ao utilizar o SDK. As etiquetas fornecem um significado semântico e permitem que os seus dados do conector se integrem perfeitamente nas experiências do Microsoft 365.

Por exemplo, diferentes ferramentas de gestão de projetos (como JIRA, Azure DevOps, Asana) podem utilizar termos diferentes para o utilizador que criou um item de trabalho, como owner, ownedByou assignedTo. Se a sua propriedade tiver um objetivo semelhante, pode atribuir a createdBy etiqueta semântica.

Pode atribuir etiquetas semânticas às propriedades de origem com a graph API ou a partir da página Atribuir etiquetas de propriedades ao utilizar o sdk. As etiquetas fornecem um significado semântico e permitem-lhe integrar os dados do conector nas experiências do Microsoft 365.

Rótulo	Descrição	Aplica-se a campos como
title	O main nome ou cabeçalho do item que pretende mostrar na pesquisa e noutras experiências.	documentTitle, ticketSubject, reportName
url	A URL de destino do item na fonte de dados. A ligação direta para abrir o item no sistema original.	documentLink, ticketUrl, recordUrl
createdBy	Identifica o utilizador que criou originalmente o item na origem de dados. Útil para filtragem e contexto.	authorEmail, submittedBy, createdByUser
lastModifiedBy	O nome do utilizador que editou recentemente o item na origem de dados.	editorEmail, updatedBy, lastChangedBy
autores	Os nomes de todas as pessoas que participaram/colaboraram no item na fonte de dados.	authorName, writer, reportAuthor
createdDateTime	A data e hora em que o item foi criado na fonte de dados.	createdOn, submissionDate, entryDate
lastModifiedDateTime	A data e hora em que o item foi modificado pela última vez na fonte de dados.	lastUpdated, modifiedOn, changeDate
fileName	O nome do ficheiro na origem de dados.	projectUrl, folderLink, groupPage
FileExtension	A extensão do ficheiro na origem de dados.	documentType, attachmentType, format
iconUrl	A URL de um ícone.	thumbnailUrl, logótipo, previewImage
containerName	O nome do contêiner. Ex.: Um projeto ou pasta do OneDrive pode ser um contentor.	projectName, folderName, groupName
containerUrl	A URL do contêiner.	projectUrl, folderLink, groupPage

Práticas recomendadas:

• Adicione tantas etiquetas quanto relevantes, mas certifique-se de que estão mapeadas com precisão.
• Não atribua uma etiqueta a uma propriedade se não corresponder ao seu objetivo: os mapeamentos incorretos degradam a experiência.

Importante

As propriedades têm de ser marcadas como recuperáveis antes de poderem ser mapeadas para etiquetas.

A title etiqueta é a mais importante. Atribuir uma propriedade a esta etiqueta permite que a ligação participe na experiência do cluster de resultados. Embora nem todas as etiquetas precisem de ser utilizadas, certifique-se de que as etiquetas que atribuir são significativas e precisas.

Relevância

A aplicação de etiquetas semânticas mapeadas com precisão melhora a deteção dos seus conteúdos através da pesquisa. A Microsoft recomenda definir o maior número possível de etiquetas seguintes, listadas por ordem descendente do seu impacto na deteção:
title, lastModifiedDateTime, lastModifiedBy, url, fileName e fileExtension.

Certifique-se de que os mapeamentos de etiquetas estão corretos. Atribuir uma etiqueta a uma propriedade que contenha conteúdo grande pode aumentar a latência da pesquisa e atrasar os resultados.

Sugestões de classificação

As sugestões de classificação podem ser aplicadas a propriedades textuais que:

• São pesquisáveis
• Não estão mapeados para etiquetas semânticas

As sugestões de classificação ajudam a priorizar determinadas propriedades nos resultados da pesquisa. Pode definir a sua importância de predefinição para muito elevada no portal de administração do Microsoft 365 Search. Estas sugestões são utilizadas juntamente com outros atributos de itens para devolver os resultados mais relevantes.

Para configurar sugestões de classificação:

1. Aceda ao separador Pesquisa e inteligência no portal de administração do Microsoft 365.
2. Selecione Personalização Otimização>por relevância.

3. Em Otimização da relevância, selecione Ver detalhes>Configurar sugestões de classificação.

4. Altere os pesos importantes nas propriedades de origem disponíveis.

Tipos de resultado padrão

As etiquetas semânticas também influenciam a forma como os tipos de resultados predefinidos são gerados. No mínimo, atribuir as title etiquetas e content garante que é criado um tipo de resultado para a sua ligação.

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

Para melhorar a experiência de resultados predefinida, defina as seguintes etiquetas quando aplicável (listadas por ordem ascendente de impacto):
title, url, lastModifiedBy, lastModifiedDateTime, fileName e fileExtension.

Lista de verificação de validação para atribuir etiquetas:

• As propriedades atribuídas a etiquetas têm de ser marcadas como recuperáveis.
• O tipo de dados da propriedade tem de corresponder ao tipo esperado para a etiqueta.
• Cada etiqueta deve ser mapeada para exatamente uma propriedade.

Aliases

Os aliases são nomes amigáveis atribuídos às propriedades. São utilizados em consultas e em filtros de propriedades refináveis para melhorar a usabilidade e a flexibilidade de consultas.

Eis alguns exemplos do mundo real:

Propriedade	Possíveis aliases	Caso de uso
createdBy	autor, proprietário, submetidoPor	Utilizadores a pedir Who wrote this? ou Who submitted?
title	assunto, cabeçalho	Utilizadores a perguntar What’s the subject of this item?
tags	etiquetas, categorias	Utilizadores a perguntar Show items tagged with Finance
filename	documentName, fileName	Utilizadores a perguntar Find file named report.docx
summary	descrição, abstrato	Utilizadores a perguntar Give me a quick overview

Melhores práticas para aliases:

• Utilize 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 content

O esquema do conector Microsoft Copilot suporta uma propriedade predefinida chamada content. Não tem de o definir no esquema como outras propriedades (por exemplo, título, etiquetas, etc.). Em vez disso, é diretamente incluído no payload do item ao ingerir dados.

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

A content propriedade é:

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

Melhores práticas para utilizar a propriedade de conteúdo:

• Adicione quaisquer dados não estruturados à content propriedade para permitir que o Copilot efetue uma pesquisa semântica e corresponda eficazmente às consultas.
• Para conteúdo não estruturado ou de forma livre, inclua propriedades como summary, comment, rootCausee description no content campo.
• Mantenha estas propriedades como campos recuperáveis separados apenas se o respetivo valor completo precisar de ser apresentado na IU.
• Pode acrescentar várias propriedades (por exemplo, summary, description) ao content campo para melhorar a compreensão semântica.

Uma amostra de como a content propriedade é utilizada ao ingerir 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 estiver a utilizar um agente declarativo (DA), deve incluir descrições de propriedades do esquema do conector Copilot no conjunto de instruções fornecido ao agente. Isto ajuda o PROMOTOR a compreender:

• O significado semântico de cada propriedade
• Como referenciar e resumir os dados
• Como responder a consultas de utilizador com 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 utilizado

Recursos de atualização de esquema

Esta secção descreve as capacidades de atualização da API de esquema .

Observação

Depois de atualizar o esquema, recomendamos que reindexe os itens para os alinhar com o esquema mais recente. Sem reingestion, o comportamento do item pode ser inconsistente.

Adicionar uma propriedade

Pode adicionar uma nova propriedade ao esquema. Embora a reingestion não seja necessária, é recomendado. Ao adicionar uma propriedade, inclua todos os atributos de pesquisa necessários.

Adicionar ou remover uma capacidade de pesquisa

Pode modificar os atributos de pesquisa de uma propriedade. No entanto:

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

Adicionar ou remover uma capacidade de pesquisa requer reingestion.

Adicionar ou remover um alias

Pode adicionar ou remover aliases para utilização em consultas de pesquisa. No entanto, os aliases que foram automaticamente criadas pelo sistema para propriedades refináveis não podem ser removidos.

Adicionar ou remover uma etiqueta semântica

Pode atribuir ou remover etiquetas semânticas. Estas etiquetas influenciam experiências como Relevância e Viva Topics.

Próximas etapas

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