Регистрация и обновление схемы для связей Microsoft Graph

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

Пример схемы

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

Свойство	Тип	Возможность поиска	Возможность запроса	Возможность извлечения	Возможность уточнения	Требуется точное соответствие	Метки	Псевдонимы
ticketId	String		✔️			✔️		Идентификатор
title	String	✔️	✔️	✔️			title
createdBy	String	✔️	✔️				createdBy	creator
assignedTo	String	✔️	✔️
lastEditedDate	DateTime		✔️	✔️	✔️		lastModifiedDateTime	editedDate
lastEditedBy	String	✔️	✔️	✔️			lastModifiedBy	edited
workItemType	String		✔️	✔️				ticketType
priority	Int64	✔️
tags	StringCollection		✔️	✔️	✔️	✔️
status	String		✔️	✔️
url	String						url
resolved	Boolean		✔️	✔️

Атрибуты свойства

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

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

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

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

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

Примечание.

Сопоставление суффиксов не поддерживается.

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

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

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

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

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

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

Если свойство поддерживает уточнение, администратор может настроить его в качестве пользовательского фильтра на странице результатов Поиска (Майкрософт). Свойство refinable не может иметь значение searchable.

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

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

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

Например, свойство ticketId является одновременно запрашиваемым и указывает точное соответствие.

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

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

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

Например, может возникнуть сценарий, в котором свойство элемента является строкой в формате GUID. Если это свойство должно соответствовать точно для запросов элементов, укажите, что isExactMatchRequired имеет значение true.

Свойство title не указывает точное соответствие. Если ничего не указано, параметр isExactMatchRequired имеет значение false. Свойство title будет токенизировано на основе правил токенизации языка содержимого элемента.

• title:Contoso Title Запрос вернет любой элемент, содержащий "Contoso" или "Title" в свойстве title.

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

Семантическая метка — это известный тег, опубликованный корпорацией Майкрософт, который можно добавить для свойства в схему. Добавление семантических меток позволяет различным продуктам Майкрософт понимать свойство и обеспечивать более удобное взаимодействие.

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

• Интеграция данных в разнородных интерфейсах
• Создание диаграмм общих знаний (например, Viva Topics)
• Шаблоны по умолчанию для пользовательских интерфейсов

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

Метка	Описание
title	Название элемента, которое вы хотите отображать в поиске и других интерфейсах.
url	Целевой URL-адрес элемента в источнике данных.
createdBy	Имя человека, создавшего элемент в источнике данных.
lastModifiedBy	Имя человека, который последним изменил элемент в источнике данных.
authors	Имена всех пользователей, которые совместно работали над элементом в источнике данных.
createdDateTime	Дата и время создания элемента в источнике данных.
lastModifiedDateTime	Дата и время последнего изменения элемента в источнике данных.
fileName	В случае с файлом — имя файла в источнике данных.
fileExtension	В случае с файлом — расширение файла в источнике данных.
iconUrl	URL-адрес значка.
containerName	Имя контейнера.
containerUrl	URL-адрес контейнера.

Например, свойство связи lastEditedBy имеет то же значение, что и метка Майкрософт lastModifiedBy.

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

Важно!

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

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

Релевантность

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

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

При обнаружении (сценариев поиска) обратите внимание на следующее:

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

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

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

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

1. На вкладке Поиск и аналитики на портале администрирования перейдите в раздел Настройка>релевантности.

2. Чтобы просмотреть список подключений, которые можно настроить, выберите Просмотреть сведения>Настройка указаний ранга.

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

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

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

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

Ваш тип результата по умолчанию обеспечивает лучший взаимодействие, если вы определяете эти метки, когда это применимо, перечисленные в порядке возрастания:

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

Наконец, назначая метки, убедитесь в следующем:

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

Псевдонимы

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

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

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

Примечание.

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

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

Вы можете добавить свойство в свою схему; это не требует повторного приема, но мы рекомендуем это.

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

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

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

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

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

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

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

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

Добавление семантической метки может повлиять на такие возможности, как релевантность и Viva Topics.

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

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