Registrar o esquema da conexão do Microsoft GraphRegister schema for the Microsoft Graph connection

O esquema de conexão determina como o seu conteúdo será usado em várias experiências do Microsoft Graph.The connection schema determines how your content will be used in various Microsoft Graph experiences. O esquema é uma lista simples de todas as propriedades que você planeja adicionar à conexão, juntamente com seus atributos, rótulos e aliases.Schema is a flat list of all the properties that you plan to add to the connection along with their attributes, labels, and aliases. Você deve registrá-lo antes de adicionar itens na conexão.You must register the schema before adding items into the connection.

Exemplo de esquemaExample schema

A tabela a seguir representa um exemplo de um esquema possível para um conector do sistema de tíquete de trabalho.The following table represents an example of a possible schema for a work ticket system connector.

PropriedadeProperty TipoType PesquisávelSearchable ConsultávelQueryable RecuperávelRetrievable RefinávelRefinable RótulosLabels AliasesAliases
ticketIdticketId Cadeia de caracteresString IDID
titletitle Cadeia de caracteresString ✔️ ✔️ ✔️ Títulotitle
createdBycreatedBy Cadeia de caracteresString ✔️ ✔️ createdBycreatedBy criadorcreator
assignedToassignedTo Cadeia de caracteresString ✔️ ✔️
lastEditedDatelastEditedDate DateTimeDateTime ✔️ ✔️ ✔️ lastModifiedDateTimelastModifiedDateTime editedDateeditedDate
lastEditedBylastEditedBy Cadeia de caracteresString ✔️ ✔️ ✔️ lastModifiedBylastModifiedBy editadoedited
workItemTypeworkItemType Cadeia de caracteresString ✔️ ✔️ ticketTypeticketType
prioridadepriority Int64Int64 ✔️
categoriastags StringCollectionStringCollection ✔️ ✔️ ✔️
statusstatus Cadeia de caracteresString ✔️ ✔️
urlurl Cadeia de caracteresString urlurl
resolvidoresolved BoolianoBoolean ✔️ ✔️

Atributos da propriedadeProperty attributes

PesquisávelSearchable

Se uma propriedade puder ser pesquisada, seu valor será adicionado ao índice de texto completo.If a property is searchable, its value is added to the full text index. Quando um usuário realiza uma pesquisa, retornamos resultados se houver uma ocorrência de pesquisa em um dos campos pesquisáveis ou seu conteúdo.When a user performs a search, we return results if there is a search hit in one of the searchable fields or its content.

Uma pesquisa por "design" exibindo resultados de acertos contra conteúdo e propriedadesA search for "design" displaying results for hits against properties and content

Uma pesquisa por "design" exibindo resultados de acertos contra conteúdo e propriedades (title, tags) e conteúdoA search for "design" displaying results for hits against properties (title, tags) and content

ConsultávelQueryable

Se uma propriedade é consultável, você pode consultá-la usando a linguagem de consulta de conhecimento (KQL).If a property is queryable, you can query against it using knowledge query language (KQL). A KQL consiste em uma ou mais palavras-chave de texto livre (palavras ou frases) ou restrições de propriedade.KQL consists of 1 or more free text keywords (words or phrases) or property restrictions. O nome da propriedade deve ser incluído na consulta, sendo especificado diretamente na consulta ou incluído de maneira programática.The property name must be included in the query, either specified in the query itself or included in the query programmatically. Você pode usar a correspondência de prefixo com o operador de caractere curinga(*).You can use prefix matching with the wildcard operator(*).

Observação

Não há suporte para correspondência de sufixo.Suffix matching is not supported.

Uma pesquisa por "search ba*" exibindo os resultados que correspondem a esse prefixo

Uma pesquisa por "search ba" exibindo os resultados que correspondem a esse prefixo*A search for "search ba" displaying results that match this prefix*

Uma pesquisa por "tags:design" fazendo o escopo dos resultados em itens com "design" na propriedade categorias

Uma pesquisa por "tags:design" fazendo o escopo dos resultados em itens com "design" na propriedade categoriasA search for "tags:design" scoping down results to items with "design" in the tags property

RecuperávelRetrievable

Se uma propriedade for recuperável, seu valor poderá ser retornado nos resultados da pesquisa.If a property is retrievable, its value can be returned in search results. As propriedades que você deseja adicionar ao modelo de exibição ou que são retornadas da consulta e sejam relevantes para os resultados da pesquisa devem ser recuperáveis.Any property that you want to add in the display template or be returned from the query and be relevant in search results must be retrievable. Marcar propriedades grandes, como editHistory, ou muitas propriedades como recuperáveis, aumentará a latência da pesquisa.Marking large properties, such as editHistory, or too many properties as retrievable will increase search latency. Seja seletivo e escolha propriedades relevantes.Be selective and choose relevant properties.

Um conjunto de propriedades recuperáveis processadas como resultado

Um conjunto de propriedades recuperáveis (title, lastEditedBy etc.) processadas como resultadoA set of retrievable properties (title, lastEditedBy etc.) rendered as a result

RefinávelRefinable

Se uma propriedade for refinável, um administrador poderá configurá-la como um filtro personalizado na página de resultados da Pesquisa da Microsoft.If a property is refinable, an admin can configure it as a custom filter in the Microsoft Search results page.

Refinar resultados por categorias, uma propriedade refinável

Refinar resultados por tags, uma propriedade refinávelRefine results by tags, a refinable property

RótulosLabels

Um rótulo é uma categoria conhecida publicada pela Microsoft que você pode adicionar a uma propriedade no seu esquema.A label is a well known tag published by Microsoft that you can add against a property in your schema. Adicionar um rótulo ajuda vários produtos da Microsoft a entender a propriedade e a oferecer uma melhor experiência.Adding a label helps various Microsoft products understand the property and provide a better experience.

RótuloLabel DescriçãoDescription
titletitle O título do item que você deseja mostrar na pesquisa e outras experiênciasThe title of the item that you want shown in search & other experiences
urlurl A URL de destino do item na fonte de dadosThe target URL of the item in the data source
createdBycreatedBy O nome da pessoa que criou o item na fonte de dadosName of the person who created the item in the data source
lastModifiedBylastModifiedBy O nome da pessoa que editou o item mais recentemente na fonte de dadosName of the person who most recently edited the item in the data source
autoresauthors Nome de todas as pessoas que participaram/trabalharam no item na fonte de dadosName of all the people who participated/collaborated on the item in the data source
createdDateTimecreatedDateTime Data e hora em que o item foi criado na fonte de dadosDate & time that the item was created in the data source
lastModifiedDateTimelastModifiedDateTime Data e hora em que o item foi modificado pela última vez na fonte de dadosDate & time the item was last modified in the data source
fileNamefileName No caso de um arquivo, o nome do arquivo na fonte de dadosIn case of a file, the name of the file in the data source
FileExtensionfileExtension No caso de um arquivo, o nome da extensão do arquivo na fonte de dadosIn case of a file, the extension of the file in the data source

Por exemplo, a propriedade de conexão lastEditedBy tem o mesmo significado que o rótulo da Microsoft lastModifiedBy.For example, the connection property lastEditedBy has the same meaning as the Microsoft label lastModifiedBy.

Adicione quantas etiquetas você puder, mas certifique-se de que elas sejam mapeadas precisamente para as propriedades.Add as many labels as you can, but ensure that they are accurately mapped to properties. Não adicione um rótulo a uma propriedade se não fizer sentido.Do not add a label to a property if it doesn't make sense. Os mapeamentos incorretos deterioram a experiência.Incorrect mappings will deteriorate the experience.

Importante

Todas as propriedades que você mapeia para rótulos devem ser recuperáveis.All properties that you map to labels must be retrievable.

RelevânciaRelevance

Aplicando o máximo possível de etiquetas mapeadas com precisão, você também pode melhorar a descoberta do seu conteúdo por meio da pesquisa.By applying as many accurately mapped labels as possible, you can also improve the discovery of your content through search. É altamente recomendável definir o maior número possível de etiquetas abaixo, listadas por um possível impacto na descoberta em ordem decrescente:We highly recommend defining as many of the below labels as possible, listed by potential impact on discovery in descending order:

  • Títulotitle
  • lastModifiedDateTimelastModifiedDateTime
  • lastModifiedBylastModifiedBy
  • urlurl
  • filenamefilename
  • FileExtensionfileExtension

Para descoberta, ou seja, cenários de pesquisa, observe:For discovery, i.e. search scenarios, please note:

  • Certifique-se de que os mapeamentos estão corretos.Ensure that your mappings are accurate.
  • Ao usar uma propriedade como um rótulo que contenha um conteúdo grande, você pode aumentar a latência da pesquisa e esperar mais tempo para a pesquisa retornar os resultados.When you use a property as label that contains large content, you might increase search latency and have to wait longer for search to return results.
  • Especialmente no cenário em que você configura uma vertical personalizada que permita a pesquisa em mais de uma conexão, os resultados da pesquisa se beneficiam com o maior número possível de etiquetas.Especially in the scenario where you configure a custom vertical that allows search over more than one connection, the search outcomes greatly benefit from appointing as many labels as possible.

Tipos de resultado padrãoDefault result types

Os rótulos também afetam a geração dos tipos de resultado padrão.Labels also affect how default result types are generated. Adicionar os rótulos de título e conteúdo no mínimo, garante que um tipo de resultado seja criado para a sua conexão.Adding the title and content labels at a minimum will ensure that a result type is created for your connection.

Um tipo de resultado padrão com título e um trecho de resultado

Um tipo de resultado padrão com title e um trecho de resultadoA default result type with title and a result snippet

O tipo de resultado padrão fornecerá uma experiência melhor quando você definir esses rótulos, quando aplicável, listados por ordem crescente:Your default result type will provide a better experience when you define these labels, when applicable, listed by ascending order:

  • Títulotitle
  • urlurl
  • lastModifiedBylastModifiedBy
  • lastModifiedDateTimelastModifiedDateTime
  • fileNamefileName
  • FileExtensionfileExtension

Por fim, ao atribuir rótulos, certifique-se do seguinte:Finally, when assigning labels, ensure the following:

  • As propriedades que você seleciona para funcionar como rótulos devem ser marcadas como recuperáveis.The properties that you select to function as labels need to be marked retrievable.
  • As propriedades e seus rótulos atribuídos devem ter o mesmo tipo de dados.The properties and their assigned labels must have the same datatype.
  • Você pode mapear exatamente um rótulo para exatamente uma propriedade.You can map exactly one label to exactly one property.

AliasesAliases

Os aliases são nomes amigáveis para as propriedades que você atribuir.Aliases are friendly names for properties that you assign. Elas serão usadas em consultas e nas seleções em filtros de propriedade refináveis.These will be used in queries and selections in refinable property filters.

Próximas etapasNext steps