Registro y administración del esquema de los conectores de Microsoft 365 Copilot

En esta guía se proporcionan instrucciones sobre cómo definir esquemas y seguir los procedimientos recomendados para Microsoft 365 Copilot conectores.

El esquema de conexión define cómo se usa el contenido en Microsoft 365 Copilot experiencias. Un esquema es una lista plana de todas las propiedades que tiene previsto agregar a la conexión. Cada propiedad incluye atributos, etiquetas y alias. Debe registrar el esquema antes de agregar elementos a la conexión.

En la tabla siguiente se muestra un esquema de ejemplo para un conector del sistema de vales de trabajo:

Propiedad	Tipo	Permite la búsqueda	Consultable	Se puede recuperar	Se puede restringir	Coincidencia exacta requerida	Etiquetas	Alias
ticketId	String		✔️			✔️		ID
title	Cadena	✔️	✔️	✔️			title
createdBy	String	✔️	✔️				createdBy	creador
assignedTo	Cadena	✔️	✔️
lastEditedDate	DateTime		✔️	✔️	✔️		lastModifiedDateTime	editedDate
lastEditedBy	String	✔️	✔️	✔️			lastModifiedBy	edited
workItemType	String		✔️	✔️				ticketType
priority	Int64	✔️
tags	StringCollection		✔️	✔️	✔️	✔️
status	Cadena		✔️	✔️
URL	Cadena						url
resolved	Booleano		✔️	✔️

Para obtener información sobre el objeto de esquema y la referencia de API, consulte la sección de esquema de la referencia de la API del conector de Copilot.

Atributos de esquema

En esta sección se describe cada atributo de esquema y se proporcionan procedimientos recomendados para usarlos.

Propiedad

Este atributo hace referencia al nombre de la propiedad .

Procedimientos recomendados:

• Usar nombres claros y únicos : asegúrese de que los nombres de propiedad sean fáciles de entender y distinguir. Evite nombres ambiguos como orgName, brOrgNameo tpOrgName. En su lugar, use nombres descriptivos como parentOrganizationName o departmentName para ayudar a Copilot a interpretar la propiedad correctamente.
• Evitar nombres demasiado técnicos o crípticos : reemplace los nombres como dataBlob o ftxInvIsLead por alternativas significativas, como incidentRootCause o qualifiedSalesLead para mejorar la legibilidad y la relevancia para las consultas de usuario.
• Agregar descripciones de propiedades : las descripciones ayudan a Copilot a comprender mejor las propiedades y a buscar coincidencias con las consultas del usuario.

Nota:

Se espera compatibilidad para agregar descripciones de propiedades a conectores personalizados en el cuarto trimestre de 2025.
Al usar agentes declarativos (DA), incluya descripciones de propiedades en el conjunto de instrucciones de da.

Permite la búsqueda

Cuando una propiedad se marca como que se puede buscar, su valor se agrega al índice de texto completo. Esto permite a Copilot devolver resultados cuando la consulta de un usuario coincide con la propiedad o su contenido.

Marque una propiedad como que se puede buscar si:

• Contiene datos textuales que es probable que los usuarios busquen.
• Es relevante para las consultas de búsqueda (por ejemplo, títulos, descripciones, etiquetas).
• Quiere que contribuya a los resultados de búsqueda y a la generación de fragmentos de código.

Ejemplos comunes:title, description, tags, , createdBy. assignedTo

Procedimientos recomendados:

• Evite marcar campos binarios grandes como que se pueden buscar.
• No marque los campos refinables como que se pueden buscar: estos atributos son mutuamente excluyentes.
• Marque solo las propiedades como que se pueden buscar si son esenciales para la relevancia de la búsqueda.

Una búsqueda de design muestra los resultados de los aciertos en la propiedad (title) y el contenido.

Consultable

Marque una propiedad como consultable si los usuarios necesitan filtrar sus resultados de búsqueda en función de valores específicos. Por ejemplo, las propiedades como ticketId, teamNameo created pueden ser consultables. Cuando un usuario consulta algo como tickets created by William, Copilot puede filtrar y devolver solo los vales pertinentes. La coincidencia de prefijos con operadores comodín (*) puede mejorar aún más la flexibilidad de búsqueda.

Marque una propiedad como consultable si:

• Se usa para filtrar o restringir los resultados de búsqueda.
• Representa datos categóricos o estructurados (por ejemplo, estado, prioridad, usuario asignado).
• Quiere admitir experiencias de búsqueda personalizadas o navegación por facetas.

Ejemplos comunes:

status (por ejemplo, abierto, cerrado), assignedTo (por ejemplo, userEmail o ID), priority (por ejemplo, alto, medio, bajo), categoryo type.

Procedimientos recomendados:

• Evite marcar campos de texto grandes (como descripciones) como consultables.
• Combine Queryable: true con Retrievable: true para que la propiedad se pueda usar y mostrar en los resultados.
• Use Refinable: true si desea que la propiedad aparezca como filtro en la interfaz de usuario.

En este ejemplo, tags se marca como consultable:

Búsqueda para tags:design determinar el ámbito de los resultados en los elementos con design en la tags propiedad .

Si se puede consultar una propiedad, puede consultarla mediante KQL (lenguaje de consulta de palabras clave). KQL admite palabras clave de texto libre y restricciones de propiedades. El nombre de propiedad debe incluirse en la consulta, ya sea de forma explícita o mediante programación. Se admite la coincidencia de prefijos con el operador comodín (*).

Nota:

No se admite la coincidencia de sufijos.

Búsqueda de la search ba\* visualización de resultados que coincidan con este prefijo.

Se puede recuperar

Marque una propiedad como recuperable si su valor debe devolverse en los resultados de la búsqueda. Cualquier propiedad que aparezca en la plantilla para mostrar o que se devuelva de una consulta debe ser recuperable. Sea selectivo: marcar demasiadas propiedades o grandes como recuperables puede aumentar la latencia de búsqueda.

Un conjunto de propiedades recuperables (title y lastEditedBy) que se representan como resultado.

Marque una propiedad como recuperable si:

• Quiere que esté visible en los resultados de la búsqueda.
• Proporciona información contextual (por ejemplo, título, estado, usuario asignado).

Ejemplos comunes:
title, summary, description, status, assignedTo, createdDateTime.

Procedimientos recomendados:

• Evite marcar campos confidenciales o irrelevantes como recuperables.
• Use Retrievable: true para los campos que se muestran en las tarjetas de búsqueda, los mensajes de Copilot o la interfaz de usuario personalizada.

Se puede restringir

Marque una propiedad como refinable si desea que se use como filtro en las experiencias de Búsqueda de Microsoft. Los administradores pueden configurar las propiedades refinables para que aparezcan como filtros personalizados en la página de resultados de búsqueda.

Cuando una propiedad es refinable:

• Se puede usar para restringir los resultados de la búsqueda.
• Aparece como un control de refinador (por ejemplo, lista desplegable o casilla) en la interfaz de usuario.
• Admite la agregación en consultas de búsqueda.

Marque una propiedad como refinable si:

• Representa datos estructurados o categóricos.
• Quiere que los usuarios filtre o agrupe los resultados por estos valores.

Ejemplos comunes:
tags (por ejemplo, finanzas, RR. HH., ingeniería), status (por ejemplo, abierto, cerrado, en curso), priority (por ejemplo, alto, medio, bajo), category, type.

Procedimientos recomendados:

• Las propiedades refinables y buscables se excluyen mutuamente; una propiedad no puede ser ambas.
• Solo los tipos de cadena o numéricos pueden ser refinables.
• Marcar demasiadas propiedades como refinables puede afectar al rendimiento.

Refine los resultados por tags, una propiedad refinable.

Coincidencia exacta requerida

Si isExactMatchRequired se establece en true para una propiedad, se indexa el valor de cadena completa. Esta configuración solo se puede aplicar a las propiedades que no se pueden buscar.

Por ejemplo, la ticketId propiedad se puede consultar y requiere una coincidencia exacta:

• ticketId:CTS-ce913b61 La consulta devuelve el elemento con el identificador de vale CTS-ce913b61.
• ticketId:CTS La consulta no devuelve el elemento con el identificador de vale CTS-ce913b61.

De forma similar, la tags propiedad también usa la coincidencia exacta:

• tags:contoso La consulta devuelve elementos con la etiqueta contoso.
• tags:contoso La consulta no devuelve elementos con la etiqueta contoso ticket.

Esto resulta especialmente útil cuando la propiedad contiene valores como GUID u otros identificadores que deben coincidir exactamente. En tales casos, establezca en isExactMatchRequiredtrue.

Si isExactMatchRequired no se especifica, el valor predeterminado falsees . Por ejemplo, la title propiedad no requiere coincidencia exacta. Se tokeniza en función de las reglas de idioma del contenido del elemento:

• title: Contoso Title La consulta devuelve elementos que contienen Contoso o Title en el título.

Etiquetas semánticas

Una etiqueta semántica es una etiqueta conocida publicada por Microsoft que puede asignar a una propiedad del esquema. Al crear un conector copilot personalizado mediante microsoft Graph API, es esencial aplicar etiquetas semánticas. Estas etiquetas ayudan a Microsoft 365 Copilot y Microsoft Search a comprender el significado y el rol de cada propiedad, lo que mejora la búsqueda, el resumen y la experiencia general del usuario.

Puede asignar etiquetas semánticas mediante el Graph API o desde la página Asignar etiquetas de propiedad al usar el SDK. Las etiquetas proporcionan significado semántico y permiten que los datos del conector se integren sin problemas en las experiencias de Microsoft 365.

Por ejemplo, las distintas herramientas de administración de proyectos (como JIRA, Azure DevOps, Asana) pueden usar términos diferentes para el usuario que creó un elemento de trabajo, como owner, ownedByo assignedTo. Si la propiedad tiene un propósito similar, puede asignar la createdBy etiqueta semántica.

Puede asignar etiquetas semánticas a las propiedades de origen mediante graph API o desde la página Asignar etiquetas de propiedad mientras usa el SDK. Las etiquetas proporcionan significado semántico y permiten integrar los datos del conector en experiencias de Microsoft 365.

Etiqueta	Descripción	Se aplica a campos como
title	Nombre principal o encabezado del elemento que desea que se muestre en la búsqueda y otras experiencias.	documentTitle, ticketSubject, reportName
url	Dirección URL de destino del elemento en el origen de datos. Vínculo directo para abrir el elemento en su sistema original.	documentLink, ticketUrl, recordUrl
createdBy	Identifica al usuario que creó originalmente el elemento en el origen de datos. Útil para el filtrado y el contexto.	authorEmail, submittedBy, createdByUser
lastModifiedBy	Nombre del usuario que ha editado recientemente el elemento en el origen de datos.	editorEmail, updatedBy, lastChangedBy
authors	Los nombres de todas las personas que han participado o colaborado en el elemento en el origen de datos.	authorName, writer, reportAuthor
createdDateTime	Fecha y hora en que se creó el elemento en el origen de datos.	createdOn, submissionDate, entryDate
lastModifiedDateTime	Fecha y hora en que el elemento se modificó por última vez en el origen de datos.	lastUpdated, modifiedOn, changeDate
fileName	Nombre del archivo en el origen de datos.	projectUrl, folderLink, groupPage
fileExtension	Extensión del archivo en el origen de datos.	documentType, attachmentType, format
iconUrl	Dirección URL de un icono.	thumbnailUrl, logo, previewImage
containerName	Nombre del contenedor. Por ejemplo: un proyecto o una carpeta de OneDrive puede ser un contenedor.	projectName, folderName, groupName
containerUrl	Dirección URL del contenedor.	projectUrl, folderLink, groupPage

Procedimientos recomendados:

• Agregue tantas etiquetas como sean pertinentes, pero asegúrese de que están asignadas con precisión.
• No asigne una etiqueta a una propiedad si no coincide con su propósito: las asignaciones incorrectas degradan la experiencia.

Importante

Las propiedades se deben marcar como recuperables para poder asignarlas a etiquetas.

La title etiqueta es la más importante. La asignación de una propiedad a esta etiqueta permite que la conexión participe en la experiencia del clúster de resultados. Aunque no es necesario usar todas las etiquetas, asegúrese de que las que asigne sean significativas y precisas.

Relevancia

La aplicación de etiquetas semánticas asignadas con precisión mejora la detectabilidad del contenido mediante la búsqueda. Microsoft recomienda definir tantas de las etiquetas siguientes como sea posible, enumeradas en orden descendente de su impacto en la detección:
title, lastModifiedDateTime, lastModifiedBy, url, fileName y fileExtension.

Asegúrese de que las asignaciones de etiquetas son precisas. Asignar una etiqueta a una propiedad que contiene contenido grande puede aumentar la latencia de búsqueda y retrasar los resultados.

Sugerencias de clasificación

Las sugerencias de clasificación se pueden aplicar a las propiedades de texto que:

• Se pueden realizar búsquedas
• No se asignan a etiquetas semánticas

Las sugerencias de clasificación ayudan a priorizar determinadas propiedades en los resultados de la búsqueda. Puede establecer su importancia de forma predeterminada en muy alta en el portal de administración de búsqueda de Microsoft 365. Estas sugerencias se usan junto con otros atributos de elemento para devolver los resultados más relevantes.

Para configurar sugerencias de clasificación:

1. Vaya a la pestaña Búsqueda e inteligencia en el portal de administración de Microsoft 365.
2. Seleccione Personalización>Ajuste de relevancia.

3. En Ajuste de relevancia, elija Ver detalles>Configure rank hints (Configurar sugerencias de clasificación).

4. Cambie las ponderaciones de importancia en las propiedades de origen disponibles.

Tipos de resultados predeterminados

Las etiquetas semánticas también influyen en cómo se generan los tipos de resultados predeterminados . Como mínimo, la asignación de las title etiquetas y content garantiza que se crea un tipo de resultado para la conexión.

Tipo de resultado predeterminado con title y un fragmento de código de resultado.

Para mejorar la experiencia de resultados predeterminada, defina las siguientes etiquetas cuando corresponda (enumeradas en orden ascendente de impacto):
title, url, lastModifiedBy, lastModifiedDateTime, fileName y fileExtension.

Lista de comprobación de validación para asignar etiquetas:

• Las propiedades asignadas a las etiquetas deben marcarse como recuperables.
• El tipo de datos de la propiedad debe coincidir con el tipo esperado para la etiqueta.
• Cada etiqueta debe asignarse exactamente a una propiedad.

Alias

Los alias son nombres descriptivos asignados a las propiedades. Se usan en consultas y en filtros de propiedades refinables para mejorar la facilidad de uso y la flexibilidad de las consultas.

Estos son algunos ejemplos del mundo real:

Propiedad	Posibles alias	Caso de uso
createdBy	author, owner, submittedBy	Usuarios que preguntan Who wrote this? o Who submitted?
title	subject, heading	Preguntas de los usuarios What’s the subject of this item?
tags	etiquetas, categorías	Preguntas de los usuarios Show items tagged with Finance
filename	documentName, fileName	Preguntas de los usuarios Find file named report.docx
summary	description, abstract	Preguntas de los usuarios Give me a quick overview

Procedimientos recomendados para alias:

• Use alias para sinónimos comunes o términos específicos del dominio.
• Evite alias demasiado genéricos o ambiguos.
• Mantenga los alias cortos e intuitivos.

Content (propiedad)

El esquema del conector Microsoft Copilot admite una propiedad predeterminada denominada content. No es necesario definirlo en el esquema como otras propiedades (por ejemplo, título, etiquetas, etc.). En su lugar, se incluye directamente en la carga del elemento al ingerir datos.

El esquema del conector Microsoft Copilot incluye una propiedad integradacontent. A diferencia de otras propiedades (como title o tags), no es necesario definirla en el esquema. En su lugar, se incluye directamente en la carga del elemento durante la ingesta de datos.

La content propiedad es:

• Semántico indexado para la búsqueda de texto.
• Se usa para generar fragmentos de código dinámicos en los resultados de la búsqueda.
• Disponible para Copilot para resumen y comprensión semántica.

Procedimientos recomendados para usar la propiedad de contenido:

• Agregue datos no estructurados a la content propiedad para permitir que Copilot realice una búsqueda semántica y coincida con las consultas de forma eficaz.
• Para el contenido no estructurado o de forma libre, incluya propiedades como summary, comment, rootCausey description en el content campo .
• Conservar estas propiedades como campos recuperables independientes solo si su valor completo debe mostrarse en la interfaz de usuario.
• Puede anexar varias propiedades (por ejemplo, summary, description) al campo para enriquecer la content comprensión semántica.

Ejemplo de cómo se usa la content propiedad al ingerir datos:

{ 
"@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" 
} 
}

Descripciones de propiedades y agentes declarativos

Si usa un agente declarativo (DA), debe incluir descripciones de propiedades del esquema del conector de Copilot en el conjunto de instrucciones proporcionado al agente. Esto ayuda al fiscal de distrito a comprender lo siguiente:

• Significado semántico de cada propiedad
• Cómo hacer referencia a los datos y resumirlos
• Respuesta a consultas de usuario mediante el contenido indexado

Defina descripciones claras y bien formadas para todas las propiedades. Una buena descripción debe explicar lo siguiente:

• Lo que representa la propiedad
• Nombres o términos alternativos
• Cuándo y cómo se debe usar

Capacidades de actualización de esquema

En esta sección se describen las funcionalidades de actualización de la API de esquema .

Nota:

Después de actualizar el esquema, se recomienda volver a indexar elementos para alinearlos con el esquema más reciente. Sin la reingestión, el comportamiento del elemento puede ser incoherente.

Agregar una propiedad

Puede agregar una nueva propiedad al esquema. Aunque la reingestión no es necesaria, se recomienda. Al agregar una propiedad, incluya todos los atributos de búsqueda necesarios.

Adición o eliminación de una funcionalidad de búsqueda

Puede modificar los atributos de búsqueda de una propiedad. Sin embargo:

• No se puede agregar un atributo refinable como parte de una actualización de esquema.
• Una propiedad no puede ser de búsqueda ni refinable.

La adición o eliminación de una funcionalidad de búsqueda requiere la reingestión.

Agregar o quitar un alias

Puede agregar o quitar alias para usarlos en consultas de búsqueda. Sin embargo, no se pueden quitar los alias creados automáticamente por el sistema para las propiedades refinables.

Agregar o quitar una etiqueta semántica

Puede asignar o quitar etiquetas semánticas. Estas etiquetas influyen en experiencias como Relevancia y Viva Topics.

Pasos siguientes

• Agregar elementos a la conexión
• Revisión de la referencia de la API de conectores de Copilot
• Buscar tipos personalizados (externalItem)