Registro y actualización del esquema para la conexión de Microsoft Graph

El esquema de conexión determina cómo se usa el contenido en diversas experiencias de Microsoft Graph. El esquema es una lista plana de todas las propiedades que planea agregar a la conexión junto con sus atributos, etiquetas y alias. Debe registrar el esquema antes de agregar elementos en la conexión.

Esquema de ejemplo

En la siguiente tabla se muestra un ejemplo de un posible esquema para el conector de un 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		✔️	✔️

Atributos de la propiedad

Permite la búsqueda

Si una propiedad se puede buscar, su valor se agrega al índice de texto completo. Cuando un usuario lleva a cabo una búsqueda, devolvemos resultados si el término se encuentra en alguno de los campos que se pueden buscar o en su contenido.

Una búsqueda de "diseño" que muestra los resultados de los aciertos en la propiedad ( title ) y el contenido.

Consultable

Si una propiedad es consultable, puede realizar consultas en ella mediante el lenguaje de consulta de conocimiento (KQL). KQL consta de una o varias palabras clave de texto libre (palabras o frases) o restricciones de propiedad. El nombre de la propiedad debe incluirse en la consulta, sea especificado en la consulta misma o incluido en la consulta por programación. Puede usar la coincidencia de prefijos con el operador comodín(*).

Nota:

No se admite la coincidencia de sufijos.

Búsqueda de "search ba*" que muestra los resultados que coinciden con este prefijo.

Búsqueda de "tags:design" que establece el ámbito de los resultados en elementos con "diseño" en la propiedad tags.

Recuperable

Si una propiedad es recuperable, se puede devolver su valor en los resultados de la búsqueda. Cualquier propiedad que quiera agregar en la plantilla para mostrar o que se devuelva de la consulta y sea relevante en los resultados de la búsqueda se debe poder recuperar. Marcar propiedades grandes o excesivas como recuperables aumenta la latencia de búsqueda. Sea selectivo y elija propiedades relevantes.

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

Se puede restringir

Si una propiedad se puede restringir, el administrador puede configurarla como filtro personalizado en la página de resultados de Búsqueda de Microsoft. Una refinable propiedad no puede ser searchable.

Restringir los resultados por tags, una propiedad restringible.

Coincidencia exacta requerida

Si isExactMatchRequired es true para una propiedad, se indizará el valor de cadena completo. isExactMatchRequired solo se puede establecer en true para las propiedades que no se pueden buscar.

Por ejemplo, la propiedad ticketId es consultable y especifica la coincidencia exacta.

• ticketId:CTS-ce913b61 La consulta devolverá el elemento con una propiedad de id. de vale CTS-ce913b61.
• ticketId:CTS La consulta NO devolverá el elemento con el identificador de vale CTS-ce913b61.

De forma similar, la propiedad tags también especifica la coincidencia exacta.

• tags:contoso La consulta devolverá cualquier elemento con la etiqueta contoso.
• tags:contoso La consulta NO devolverá elementos con la etiqueta contoso ticket.

Por ejemplo, puede haber un escenario en el que la propiedad item sea una cadena con formato GUID. Si esta propiedad debe coincidir exactamente con las consultas de elementos, especifique que isExactMatchRequired es true.

La propiedad title no especifica la coincidencia exacta. Si no se especifica nada, isExactMatchRequired es false. La propiedad title se tokenizará en función de las reglas de tokenización del idioma del contenido del elemento.

• title:Contoso Title La consulta devolverá cualquier elemento que contenga "Contoso" o "Title" en la propiedad title.

Etiquetas semánticas

Una etiqueta semántica es una etiqueta conocida publicada por Microsoft que puede agregar en una propiedad del esquema. Agregar una etiqueta semántica ayuda a varios productos de Microsoft a comprender la propiedad y proporcionar una mejor experiencia.

Las etiquetas semánticas proporcionan un enfoque independiente del dominio para asignar propiedades de diferentes dominios de contenido a un conjunto de clases conocidas. Encuentran aplicaciones en muchas experiencias de contenido diferentes y proporcionan compatibilidad automatizada con tareas como son:

• Integración de datos en experiencias heterogéneas
• Creación de gráficos de conocimiento comunes (por ejemplo, Viva Topics)
• Plantillas predeterminadas para experiencias de usuario

Puede asignar etiquetas semánticas a las propiedades de origen en la página Asignar etiquetas de propiedades. Las etiquetas proporcionan significado semántico y permiten integrar los datos del conector en experiencias de Microsoft 365.

Etiqueta	Description
title	El título del elemento que desea que se muestre en la búsqueda y otras experiencias.
url	Dirección URL de destino del elemento en el origen de datos.
createdBy	Nombre de la persona que creó el elemento en el origen de datos.
lastModifiedBy	Nombre de la persona que editó el elemento más recientemente en el origen de datos.
authors	Los nombres de todas las personas que han participado o colaborado en el elemento en el origen de datos.
createdDateTime	Fecha y hora en que se creó el elemento en el origen de datos.
lastModifiedDateTime	Fecha y hora en que el elemento se modificó por última vez en el origen de datos.
fileName	En el caso de un archivo, el nombre del archivo en el origen de datos.
fileExtension	En el caso de un archivo, la extensión del archivo en el origen de datos.
iconUrl	Dirección URL de un icono.
containerName	Nombre del contenedor.
containerUrl	Dirección URL del contenedor.

Por ejemplo, la propiedad de conexión lastEditedBy tiene el mismo significado que la etiqueta de Microsoft lastModifiedBy.

Agregue todas las etiquetas que pueda, pero asegúrese de que estén correctamente asignadas a las propiedades. No agregue una etiqueta a una propiedad si no tiene sentido. Las asignaciones incorrectas degradan la experiencia.

Importante

Todas las propiedades que asigne a las etiquetas deben ser recuperables.

El título de la etiqueta es la etiqueta más importante. Asegúrese de asignar una propiedad a esta etiqueta para permitir que la conexión participe en la experiencia del clúster de resultados. La asignación incorrecta de etiquetas degrada la experiencia de búsqueda. Es correcto que algunas etiquetas no tengan una propiedad asignada.

Relevancia

Al aplicar tantas etiquetas correctamente asignadas como sea posible, podrá también mejorar la detección del contenido a través de la búsqueda. Se recomienda definir tantas etiquetas como sea posible, enumeradas por el posible impacto en la detección en orden descendente:

• title
• lastModifiedDateTime
• lastModifiedBy
• url
• fileName
• fileExtension

Para la detección (escenarios de búsqueda), debe tenerse en cuenta lo siguiente:

• Asegúrese de que las asignaciones sean correctas.
• Cuando se usa una propiedad como etiqueta que contiene contenido grande, puede aumentar la latencia de búsqueda y tener que esperar más tiempo para que la búsqueda devuelva resultados.
• Especialmente en el escenario en el que se configura una vertical personalizada que permite la búsqueda en más de una conexión, los resultados de la búsqueda se benefician en gran medida de designar tantas etiquetas como sea posible.

Tipos de resultados predeterminados

Las etiquetas también afectan la forma en que se generan los tipos de resultado predeterminado. Al agregar el título y las etiquetas de contenido como mínimo, se 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.

El tipo de resultado predeterminado proporciona una mejor experiencia al definir estas etiquetas, cuando corresponda, enumeradas en orden ascendente:

• title
• url
• lastModifiedBy
• lastModifiedDateTime
• fileName
• fileExtension

Por último, cuando asigne etiquetas, asegúrese de lo siguiente:

• Las propiedades que seleccione para que funcionen como etiquetas deben marcarse como recuperables.
• Las propiedades y sus etiquetas asignadas deben tener el mismo tipo de base de datos.
• Puede asignar exactamente una etiqueta a una propiedad.

Alias

Los alias son nombres descriptivos para las propiedades que usted asigna. Se usan en consultas y selecciones en filtros de propiedades refinables.

Capacidades de actualización de esquema

En esta sección se incluye información sobre las capacidades de actualización de la API del esquema.

Nota:

Se recomienda reingerir elementos después de una actualización para llevarlos al esquema más reciente. Sin reingestión, el comportamiento de los elementos será incoherente.

Agregar una propiedad

Puede agregar una propiedad al esquema; si lo hace, no es necesario volver a realizar la ingesta, pero ello se recomienda.

Al agregar una propiedad, puede incluir todos los atributos de búsqueda que necesite.

Agregar o quitar una funcionalidad de búsqueda

Puede agregar atributos de búsqueda específicos a una propiedad, pero tenga en cuenta que no puede agregar un atributo de búsqueda de refinador como cambio de esquema. Además, no es posible usar atributos refinables como capacidades de búsqueda.

Agregar una funcionalidad de búsqueda requiere reingestión.

Agregar o quitar un alias

Puede agregar o quitar alias y usarlos para las consultas de búsqueda.

Tenga en cuenta que no puede quitar el alias original de una propiedad refinable creada automáticamente por el sistema.

Agregar o quitar una etiqueta semántica

Agregar una etiqueta semántica puede afectar a experiencias como Relevancia y Viva Topics.

Pasos siguientes

• Agregar elementos a la conexión
• Revisar la referencia de la API de conectores de Microsoft Graph
• Buscar tipos personalizados (externalItem)
• Crear el primer conector de Microsoft Graph personalizado