Регистрация схемы для соединителей Microsoft 365 Copilot и управление ими

В этом руководстве содержатся рекомендации по определению схем и рекомендации по Microsoft 365 Copilot соединителей.

Схема подключения определяет, как содержимое используется в Microsoft 365 Copilot взаимодействиях. Схема — это плоский список всех свойств, которые планируется добавить в соединение. Каждое свойство включает атрибуты, метки и псевдонимы. Необходимо зарегистрировать схему перед добавлением элементов в соединение.

В следующей таблице показан пример схемы для соединителя системы рабочих билетов.

Сведения об объекте схемы и справочнике по API см. в разделе схема справочника по API Соединителя Copilot.

Атрибуты схемы

В этом разделе описаны все атрибуты схемы и приведены рекомендации по их использованию.

Property

Этот атрибут ссылается на имя свойства.

Рекомендации

• Используйте четкие и уникальные имена . Убедитесь, что имена свойств просты в понимании и различии. Избегайте неоднозначных имен, таких как orgName, brOrgNameили tpOrgName. Вместо этого используйте описательные имена, такие как parentOrganizationName или departmentName , чтобы помочь Copilot правильно интерпретировать свойство.
• Избегайте слишком технических или загадочных имен . Замените имена, такие как dataBlob или ftxInvIsLead значимыми альтернативами, такими как incidentRootCause или , qualifiedSalesLead чтобы повысить удобочитаемость и релевантность запросов пользователей.
• Добавление описаний свойств — описания помогают Copilot лучше понять и сопоставить свойства с пользовательскими запросами.

Возможность поиска

Если свойство помечается как доступное для поиска, его значение добавляется в полнотекстовый индекс. Это позволяет Copilot возвращать результаты, когда запрос пользователя соответствует свойству или его содержимому.

Пометьте свойство как доступный для поиска, если:

• Он содержит текстовые данные, которые пользователи, скорее всего, будут искать.
• Это относится к поисковым запросам (например, заголовки, описания, теги).
• Вы хотите, чтобы он способствовал поиску хитов и созданию фрагментов.

Распространенные примеры:title , description, tags, createdBy, assignedTo.

Рекомендации

• Не помечайте большие двоичные поля как доступные для поиска.
• Не помечайте уточняемые поля как доступные для поиска — эти атрибуты являются взаимоисключающими.
• Пометьте свойства как доступные для поиска, только если они необходимы для релевантности поиска.

При поиске design отображаются результаты попаданий в свойство (title) и содержимое.

Возможность запроса

Пометьте свойство как запрашиваемое , если пользователям нужно фильтровать результаты поиска на основе определенных значений. Например, такие свойства, как ticketId, teamNameили created , могут быть запрашиваемыми. Когда пользователь запрашивает что-то вроде tickets created by William, Copilot может фильтровать и возвращать только соответствующие билеты. Сопоставление префиксов с операторами с подстановочными знаками (*) может еще больше повысить гибкость поиска.

Пометка свойства как запрашиваемого, если:

• Он используется для фильтрации или сужения результатов поиска.
• Он представляет категориальные или структурированные данные (например, состояние, приоритет, назначенный пользователь).
• Вы хотите поддерживать пользовательские возможности поиска или фасетную навигацию.

Распространенные примеры:

status (например, open, closed), assignedTo (например, userEmail или ID), priority (например, high, medium, low), categoryили type.

Рекомендации

• Избегайте маркировки больших текстовых полей (например, описаний) как доступных для запросов.
• Объедините Queryable: true с Retrievable: true , чтобы свойство можно было использовать и отображать в результатах.
• Используйте, Refinable: true если нужно, чтобы свойство отображалось в качестве фильтра в пользовательском интерфейсе.

В этом примере помечается tags как запрашиваемый:

Поиск для tags:design определения области результатов до элементов с design в свойстве tags .

Если свойство доступно для запросов, вы можете выполнить запрос к нему с помощью KQL (язык запросов ключевых слов). KQL поддерживает ключевые слова свободного текста и ограничения свойств. Имя свойства должно быть включено в запрос явным или программным способом. Поддерживается сопоставление префикса с оператором с подстановочными знаками (*).

Поиск для search ba\* отображения результатов, соответствующих этому префиксу.

Возможность извлечения

Пометьте свойство как извлекаемое , если его значение должно быть возвращено в результатах поиска. Любое свойство, которое отображается в шаблоне отображения или возвращается из запроса, должно быть извлечено. Будьте селективными. Маркировка слишком большого или большого количества свойств как извлекаемых может увеличить задержку поиска.

Набор свойств, доступных для извлечения (title и lastEditedBy), отображаемый в качестве результата.

Пометка свойства как извлекаемого, если:

• Вы хотите, чтобы он был виден в результатах поиска.
• Он предоставляет контекстную информацию (например, заголовок, состояние, назначенный пользователь).

Распространенные примеры:
title, summary, description, status, assignedTo, createdDateTime.

Рекомендации

• Избегайте маркировки конфиденциальных или нерелевантных полей как извлекаемых.
• Используйте Retrievable: true для полей, отображаемых в карточках поиска, запросах Copilot или пользовательском интерфейсе.

Возможность уточнения

Пометьте свойство как уточняющее , если вы хотите, чтобы оно использовалось в качестве фильтра в интерфейсах поиска (Майкрософт). Администраторы могут настроить уточняющие свойства так, чтобы они отображались в качестве настраиваемых фильтров на странице результатов поиска.

Если свойство можно уточнить:

• Его можно использовать для сужения результатов поиска.
• Он отображается как элемент управления уточнения (например, раскрывающийся список или флажок) в пользовательском интерфейсе.
• Он поддерживает агрегирование в поисковых запросах.

Пометка свойства как уточняемого, если:

• Он представляет категориальные или структурированные данные.
• Пользователи должны фильтровать или группировать результаты по этим значениям.

Распространенные примеры:
tags (например, finance, HR, engineering), status (например, open, closed, in progress), priority (например, high, medium, low), category, type.

Рекомендации

• Уточняемые и доступные для поиска взаимоисключающие — свойство не может быть и тем, и другим.
• Уточнять можно только строковые или числовые типы .
• Маркировка слишком большого количества свойств как уточняемых может повлиять на производительность.

Уточняйте результаты с помощью tagsсвойства , которое можно уточнить.

Требуется точное соответствие

Если isExactMatchRequired для свойства задано значение , true индексируется полное строковое значение. Этот параметр можно применить только к свойствам, которые недоступны для поиска.

Например, ticketId свойство можно запрашивать и требует точного сопоставления:

• ticketId:CTS-ce913b61 Запрос возвращает элемент с идентификатором билета CTS-ce913b61.
• ticketId:CTS Запрос не возвращает элемент с идентификатором билета CTS-ce913b61.

Аналогичным образом свойство tags также использует точное сопоставление:

• tags:contoso Запрос возвращает элементы с тегом contoso.
• tags:contoso Запрос не возвращает элементы с билетом contoso тега.

Это особенно полезно, если свойство содержит такие значения, как идентификаторы GUID или другие идентификаторы, которые должны быть точно совпадать. В таких случаях задайте значение isExactMatchRequiredtrue.

Если isExactMatchRequired параметр не указан, по умолчанию используется значение false. Например, свойство titleне требует точного сопоставления. Он токенизируется на основе языковых правил содержимого элемента:

• title: Contoso Title Запрос возвращает элементы, содержащие Contoso или Title в заголовке.

Семантические метки

Семантическая метка — это хорошо известный тег, опубликованный корпорацией Майкрософт, который можно назначить свойству в схеме. При создании пользовательского соединителя Copilot с помощью API Graph Майкрософт применение семантических меток имеет важное значение. Эти метки помогают Microsoft 365 Copilot и поиску Майкрософт понять значение и роль каждого свойства, улучшая поиск, суммирование и общее взаимодействие с пользователем.

Вы можете назначить семантические метки с помощью API Graph или на странице Назначение меток свойств при использовании пакета SDK. Метки обеспечивают семантическое значение и позволяют данным соединителя легко интегрироваться в интерфейс Microsoft 365.

Например, различные средства управления проектами (например, JIRA, Azure DevOps, Asana) могут использовать разные термины для пользователя, создавшего рабочий элемент, например owner, ownedByили assignedTo. Если свойство служит аналогичной цели, можно назначить семантическую createdBy метку.

Вы можете назначить семантические метки свойствам источника с помощью API графа или на странице Назначение меток свойств при использовании пакета SDK. Метки обеспечивают семантическое значение и позволяют интегрировать данные соединителя в интерфейс Microsoft 365.

Рекомендации

• Добавьте столько меток, сколько нужно, но убедитесь, что они точно сопоставлены.
• Не назначайте метку свойству, если оно не соответствует его назначению. Неправильные сопоставления ухудшают взаимодействие.

Метка title является наиболее важной. Назначение свойства этой метке позволяет подключению участвовать в работе результирующих кластеров. Хотя не все метки необходимо использовать, убедитесь, что назначенные метки являются значимыми и точными.

Важность

Применение точно сопоставленных семантических меток повышает доступность обнаружения содержимого с помощью поиска. Корпорация Майкрософт рекомендует определить как можно больше следующих меток, перечисленных в порядке убывания их влияния на обнаружение:
title, lastModifiedDateTime, lastModifiedBy, url, fileName и fileExtension.

Убедитесь, что сопоставления меток являются точными. Назначение метки свойству, содержащему большое содержимое, может увеличить задержку поиска и результаты задержки.

Указания ранжирования

Указания ранжирования можно применять к текстовым свойствам, которые:

• Доступны для поиска
• Не сопоставлены с семантические метки

Указания ранжирования помогают определить приоритеты определенных свойств в результатах поиска. На портале администрирования Поиска Microsoft 365 их важность по умолчанию можно задать очень высокий . Эти указания используются вместе с другими атрибутами элемента для возврата наиболее релевантных результатов.

Чтобы настроить указания ранга, выполните следующие действия:

1. Перейдите на вкладку Поиск и аналитика на портале администрирования Microsoft 365.
2. Выберите Настройка>релевантности.

3. В разделе Настройка релевантности выберите Просмотр сведений>Настройка указаний ранга.

4. Измените вес важности для доступных свойств источника.

Типы результатов по умолчанию

Семантические метки также влияют на то, как создаются типы результатов по умолчанию . Как минимум, назначение title меток и content гарантирует, что для подключения будет создан тип результата.

Тип результата по умолчанию с title и фрагментом результата.

Чтобы улучшить работу с результатом по умолчанию, при необходимости определите следующие метки (перечисленные в порядке по возрастанию влияния):
title, url, lastModifiedBy, lastModifiedDateTime, fileName и fileExtension.

Контрольный список проверки для назначения меток:

• Свойства, назначенные меткам, должны быть помечены как извлекаемые.
• Тип данных свойства должен соответствовать ожидаемому типу метки.
• Каждая метка должна быть сопоставлена с одним свойством.

Псевдонимы

Псевдонимы — это понятные имена, присваиваемые свойствам. Они используются в запросах и в фильтрах свойств с возможностью уточнения для повышения удобства использования и гибкости запросов.

Ниже приведены некоторые реальные примеры:

Рекомендации по псевдонимам:

• Используйте псевдонимы для распространенных синонимов или терминов, относящихся к предметной области.
• Избегайте слишком общих или неоднозначных псевдонимов.
• Держите псевдонимы короткими и интуитивно понятными.

Свойство Content

Схема соединителя Microsoft Copilot поддерживает свойство по умолчанию с именем content. Вам не нужно определять его в схеме, как и другие свойства (например, заголовок, теги и т. д.). Вместо этого он непосредственно включается в полезные данные элемента при приеме данных.

Схема соединителя Microsoft Copilot включает встроенное content свойство. В отличие от других свойств (например title , или tags), его не нужно определять в схеме. Вместо этого он включается непосредственно в полезные данные элемента во время приема данных.

Свойство content имеет следующий тип:

• Семантически индексируется для поиска текста.
• Используется для создания динамических фрагментов в результатах поиска.
• Доступно для Copilot для сводных данных и понимания семантики.

Рекомендации по использованию свойства содержимого:

• Добавьте в свойство любые неструктурированные данныеcontent, чтобы позволить Copilot эффективно выполнять семантический поиск и сопоставлять запросы.
• Для неструктурированного содержимого или содержимого в свободной форме включите в поле такие свойства, как summary, comment, rootCauseи description .content
• Сохраните эти свойства в виде отдельных извлекаемых полей , только если их полное значение должно отображаться в пользовательском интерфейсе.
• В поле можно добавить несколько свойств (например, summary, ), descriptioncontent чтобы расширить семантическое понимание.

Пример content использования свойства при приеме данных:

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

"properties": { 
"title": "Payment Gateway Error", 
"priority": "High", 
"assignee": "[email protected]" 
}, 

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

Декларативные агенты и описания свойств

Если вы используете декларативный агент (DA), следует включить описания свойств из схемы соединителя Copilot в набор инструкций , предоставленный агенту. Это помогает DA понять:

• Семантическое значение каждого свойства
• Как сослаться на данные и обобщить их
• Как отвечать на запросы пользователей с помощью индексированного содержимого

Определите четкие, правильно сформированные описания для всех свойств. Хорошее описание должно объяснить:

• Что представляет свойство
• Любые альтернативные имена или термины
• Когда и как его следует использовать

Возможности обновления схемы

В этом разделе описываются возможности обновления API схемы .

Добавить свойство

В схему можно добавить новое свойство. Хотя повторный прием не требуется, рекомендуется. При добавлении свойства включите все необходимые атрибуты поиска.

Добавление или удаление возможности поиска

Атрибуты поиска для свойства можно изменить. Однако:

• Вы не можете добавить уточняемый атрибут в рамках обновления схемы.
• Свойство не может быть одновременно доступны для поиска и уточнения.

Для добавления или удаления возможности поиска требуется повторный прием.

Добавление или удаление псевдонима

Вы можете добавлять или удалять псевдонимы для использования в поисковых запросах. Однако псевдонимы, которые были автоматически созданы системой для уточняемых свойств , не могут быть удалены.

Добавление или удаление семантической метки

Вы можете назначать или удалять семантические метки. Эти метки влияют на такие возможности, как релевантность и Viva Topics.

Дальнейшие действия

• Добавление элементов в связь
• Ознакомьтесь со справочником по API соединителей Copilot.
• Поиск объектов настраиваемого типа (externalItem)