Registrar e atualizar o esquema para a Microsoft Graph conexão

O esquema de conexão determina como seu conteúdo é usado em várias experiências do Microsoft Graph. O esquema é uma lista simples de todas as propriedades que você planeja adicionar à conexão junto com seus atributos, rótulos e aliases. Você deve registrá-lo antes de adicionar itens na conexão.

Exemplo de esquema

A tabela a seguir representa um exemplo de um esquema possível para um conector do sistema de tíquete de trabalho.

Propriedade	Tipo	Pesquisável	Consultável	Recuperável	Refinável	Correspondência Exata Necessária	Rótulos	Aliases
ticketId	Cadeia de caracteres		✔️			✔️		ID
title	Cadeia de caracteres	✔️	✔️	✔️			Título
createdBy	Cadeia de caracteres	✔️	✔️				createdBy	criador
assignedTo	Cadeia de caracteres	✔️	✔️
lastEditedDate	DateTime		✔️	✔️	✔️		lastModifiedDateTime	editedDate
lastEditedBy	Cadeia de caracteres	✔️	✔️	✔️			lastModifiedBy	editado
workItemType	Cadeia de caracteres		✔️	✔️				ticketType
prioridade	Int64	✔️
categorias	StringCollection		✔️	✔️	✔️	✔️
status	Cadeia de caracteres		✔️	✔️
url	Cadeia de caracteres						url
resolvido	Booliano		✔️	✔️

Atributos da propriedade

Pesquisável

Se uma propriedade puder ser pesquisada, seu valor será adicionado ao índice de texto completo. 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.

Uma pesquisa por "design" exibindo resultados de ocorrências contra a propriedade (title) e conteúdo.

Consultável

Se uma propriedade é consultável, você pode consultá-la usando a linguagem de consulta de conhecimento (KQL). KQL consiste em uma ou mais palavras-chave de texto livre (palavras ou frases) ou restrições de propriedade. O nome da propriedade deve ser incluído na consulta, sendo especificado diretamente na consulta ou incluído de maneira programática. Você pode usar a correspondência de prefixo com o operador de caractere curinga(*).

Observação

A correspondência de sufixos não é suportada.

Uma pesquisa por "search ba*" a apresentar resultados que correspondem a este prefixo.

Uma pesquisa por "tags:design" reduz os resultados para itens com "design" na propriedade tags.

Recuperável

Se uma propriedade for recuperável, seu valor poderá ser retornado nos resultados da pesquisa. 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. Marcar propriedades grandes ou demais como recuperáveis aumenta a latência da pesquisa. Seja seletivo e escolha propriedades relevantes.

Um conjunto de propriedades recuperáveis (title e lastEditedBy) renderizadas como resultado.

Refinável

Se uma propriedade for refinável, um administrador poderá configurá-la como um filtro personalizado na página de resultados da Pesquisa da Microsoft. Uma refinable propriedade não pode ser searchable.

Refinar resultados por tags, uma propriedade refináveis.

Correspondência exata necessária

Se isExactMatchRequired for true para uma propriedade, o valor completo da cadeia é indexado. isExactMatchRequired só pode ser definido como true para propriedades não pesquisáveis.

Por exemplo, a propriedade ticketId é consultada e especifica a correspondência exata.

• A consulta ticketId:CTS-ce913b61 devolve o item com uma propriedade de ID de permissão CTS-ce913b61.
• A consulta ticketId:CTS não devolve o item com o ID do pedido CTS-ce913b61.

Da mesma forma, a propriedade tags também especifica a correspondência exata.

• A consulta tags:contoso devolve qualquer item com a etiqueta contoso.
• A consulta tags:contoso não devolve itens com a permissão de etiqueta contoso.

Por exemplo, pode haver um cenário em que a propriedade item é uma cadeia formatada com GUID. Se esta propriedade tiver de ser correspondida exatamente para consultas de itens, especifique que isExactMatchRequired é true.

A propriedade de título não especifica a correspondência exata. Se nada for especificado, isExactMatchRequired é false. A propriedade de título é token com base nas regras de tokenização do idioma do conteúdo do item.

• A consulta title:Contoso Title devolve qualquer item que contenha Contoso ou Title na propriedade de título .

Rótulos semânticos

Um rótulo semântico é uma marca conhecida publicada pela Microsoft que você pode adicionar em relação a uma propriedade em seu esquema. Adicionar um rótulo semântico ajuda vários produtos da Microsoft a entender a propriedade e fornecer uma experiência melhor.

Os rótulos semânticos fornecem uma abordagem independente de domínio para atribuir propriedades de diferentes domínios de conteúdo a um conjunto de classes conhecidas. Eles localizam aplicativos em muitas experiências de conteúdo diferentes e fornecem suporte automatizado para tarefas como:

• Integração de dados em experiências heterogêneas
• Criar gráficos de conhecimentos comuns (por exemplo, Viva Topics)
• Modelos padrão para experiências do usuário

Você pode atribuir rótulos semânticos às propriedades de origem atribuir rótulos de página. Os rótulos fornecem significado semântico e permitem que você integre seus dados de conector às experiências do Microsoft 365.

Rótulo	Descrição
title	O título do item que você deseja mostrar na pesquisa e em outras experiências.
url	A URL de destino do item na fonte de dados.
createdBy	O nome da pessoa que criou o item na fonte de dados.
lastModifiedBy	O nome da pessoa que editou mais recentemente o item na fonte de dados.
autores	Os nomes de todas as pessoas que participaram/colaboraram no item na fonte de dados.
createdDateTime	A data e hora em que o item foi criado na fonte de dados.
lastModifiedDateTime	A data e hora em que o item foi modificado pela última vez na fonte de dados.
fileName	No caso de um arquivo, o nome do arquivo na fonte de dados.
FileExtension	No caso de um arquivo, a extensão do arquivo na fonte de dados.
iconUrl	A URL de um ícone.
containerName	O nome do contêiner.
containerUrl	A URL do contêiner.

Por exemplo, a propriedade de conexão lastEditedBy tem o mesmo significado que o rótulo da Microsoft lastModifiedBy.

Adicione quantas etiquetas você puder, mas certifique-se de que elas sejam mapeadas precisamente para as propriedades. Não adicione uma etiqueta a uma propriedade se não fizer sentido. Mapeamentos incorretos degradam a experiência.

Importante

Todas as propriedades que você mapeia para rótulos devem ser recuperáveis.

O rótulo título é o rótulo mais importante. Certifique-se de atribuir uma propriedade a esse rótulo para permitir que sua conexão participe da experiência do cluster de resultados. O mapeamento incorreto de rótulos prejudica a experiência de pesquisa. Não há problema em alguns rótulos não terem uma propriedade atribuída a eles.

Relevância

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. É altamente recomendável definir o maior número possível dos seguintes rótulos, listados por impacto potencial na descoberta em ordem decrescente:

• Título
• lastModifiedDateTime
• lastModifiedBy
• url
• fileName
• FileExtension

Para descoberta (cenários de pesquisa), observe o seguinte:

• Certifique-se de que os mapeamentos estão corretos.
• Ao usar uma propriedade como um rótulo que contém conteúdo grande, você pode aumentar a latência da pesquisa e ter que esperar mais tempo para que a pesquisa retorne os resultados.
• Especialmente no cenário em que você configura uma vertical personalizada que permite a pesquisa em mais de uma conexão, os resultados da pesquisa se beneficiam muito ao indicar o maior número possível de rótulos.

Sugestões de classificação

As sugestões de classificação podem ser aplicadas a propriedades textuais que não estão mapeadas para etiquetas semânticas e são definidas como pesquisáveis. Podem ser definidas num intervalo entre predefinição e muito alta no portal de administração da Pesquisa. As sugestões são consumidas com outros atributos de cada item, para devolver os itens mais relevantes para uma determinada consulta.

Utilize os seguintes passos para definir sugestões de classificação:

1. Aceda ao separador Pesquisa e inteligência no portal de administração.
2. Selecione Personalização Otimização>por relevância.

2. Para ver uma lista de ligações que podem ser otimizadas, selecione Ver Detalhes>Configurar sugestões de classificação.

3. Altere os pesos importantes nas propriedades de origem disponíveis.

Tipos de resultado padrão

Os rótulos também afetam a geração dos tipos de resultado padrão. Adicionar o título e as etiquetas de conteúdo no mínimo garante que é criado um tipo de resultado para a sua ligação.

Um tipo de resultado padrão com title e um trecho de resultado.

Seu tipo de resultado padrão oferece uma experiência melhor ao definir esses rótulos, quando aplicáveis, listados em ordem crescente:

• Título
• url
• lastModifiedBy
• lastModifiedDateTime
• fileName
• FileExtension

Por fim, ao atribuir rótulos, certifique-se do seguinte:

• As propriedades que você seleciona para funcionar como rótulos devem ser marcadas como recuperáveis.
• As propriedades e seus rótulos atribuídos devem ter o mesmo tipo de dados.
• Você pode mapear exatamente um rótulo para exatamente uma propriedade.

Aliases

Os aliases são nomes amigáveis para as propriedades que você atribuir. Eles são usados em consultas e seleções em filtros de propriedades refináveis.

Recursos de atualização de esquema

Esta seção inclui informações sobre os recursos de atualização da API do esquema.

Observação

Recomendamos que você reinsira os itens após uma atualização para trazê-los para o esquema mais recente. Sem reingestion, o comportamento dos itens é inconsistente.

Adicionar uma propriedade

Pode adicionar uma propriedade ao esquema; Fazê-lo não requer reposição, mas recomendamos que o faça.

Ao adicionar uma propriedade, você pode incluir todos os atributos de pesquisa necessários.

Adicionar/remover um recurso de pesquisa

Pode adicionar atributos de pesquisa específicos a uma propriedade, mas tenha em atenção que não pode adicionar um atributo de pesquisa de refinador como uma alteração de esquema. Além disso, não é possível utilizar atributos refináveis como capacidades pesquisáveis.

Adicionar um recurso de pesquisa requer reingestão.

Adicionar/remover um alias

Você pode adicionar ou remover aliases e usá-los para suas consultas de pesquisa.

Considere que não pode remover o alias original de uma propriedade refinável que foi criada automaticamente pelo sistema.

Adicionar/remover um rótulo semântico

Adicionar uma etiqueta semântica pode afetar experiências como Relevância e Viva Topics.

Próximas etapas

• Adicionar itens à conexão
• Revisar a referência da API do conectores do Microsoft Graph
• Pesquisar tipos personalizados (externalItem)
• Criar seu primeiro conector Microsoft Graph personalizado