Criar, atualizar e excluir conexões no Microsoft Graph

Artigo
11/07/2024

A plataforma de conectores do Microsoft Graph oferece uma maneira intuitiva de adicionar seus dados externos ao Microsoft Graph. Uma conexão é um contêiner lógico de dados externos que um administrador pode gerenciar como uma única unidade.

Após a criação de uma ligação, pode adicionar os seus conteúdos a partir de qualquer origem de dados externa, como uma origem de conteúdo no local ou um serviço de software como serviço (SaaS) externo. Só é possível exibir e gerenciar as conexões que você criou ou que foram explicitamente autorizadas para gerenciamento. Um administrador de pesquisa pode exibir e gerenciar todas as conexões no locatário no Centro de Administração Moderna.

Exemplo de estrutura do Conector de Pedidos de Suporte Técnico personalizado.

Amostra de um sistema de assistência técnica personalizado da Estrutura de Conector de Tíquetes.

Modo de exibição de administrador das conexões, incluindo o Conector de Tíquetes personalizado.

Modo de exibição de administrador das conexões, incluindo o Conector de Tíquetes personalizado.

Você pode modelar uma conexão da maneira que quiser mas criar uma conexão para cada instância do seu conector é o modelo mais comum. Por exemplo, cada vez que você configurar o conector de compartilhamento de arquivos do Microsoft Windows, uma nova conexão é criada. Você também pode criar uma única conexão para adicionar todos os itens da fonte de dados. Por exemplo, v pode criar uma única conexão para adicionar todos os tíquetes e incidentes em várias equipes a partir de seu sistema de assistência técnica.

Estados e operações

A conexão pode existir em um dos seguintes estados.

Estado	Descrição
Rascunho	É fornecida uma conexão vazia. Nenhuma das definições, esquema ou origem de dados estão configuradas.
Pronto	A conexão é fornecida com o esquema registrado e está pronta para inclusão.
Obsoleto	Isso ocorre quando um recurso dependente, como uma API, foi preterido. A exclusão da conexão é a única operação válida.
LimitExceeded	Se atingir o limite máximo de uma única ligação ou a quota ao nível do inquilino em todas as ligações, não poderá adicionar mais itens até sair do estado.

A tabela a seguir especifica quais operações estão disponíveis em cada Estado.

Operação	Rascunho	Pronto	Obsoleto	LimitExceeded
Criar conexão	❌	✔️	❌	✔️
Ler conexão	✔️	✔️	✔️	✔️
Atualizar conexão	✔️	✔️	❌	✔️
Excluir conexão	✔️	✔️	✔️	✔️
Criar esquema	✔️	❌	❌	❌
Ler esquema	❌	✔️	✔️	✔️
Atualizar esquema	❌	❌	❌	❌
Excluir esquema	❌	❌	❌	❌
Criar item	❌	✔️	❌	❌
Ler item	❌	✔️	✔️	✔️
Atualizar item	❌	✔️	❌	✔️
Excluir item	❌	✔️	❌	✔️

Uma conexão permite que seu aplicativo defina um esquema para os itens que serão indexados, e que ele forneça um ponto de extremidade para o seu serviço adicionar, atualizar ou excluir itens do índice.

Criar uma conexão é a primeira etapa para um aplicativo para adicionar itens ao índice de pesquisa.

Criar uma conexão

Antes que um aplicativo possa adicionar itens ao índice de pesquisa, ele deve criar e configurar uma conexão:

Criar uma conexão com ID exclusiva, nome de exibição e descrição.
Registre um esquema para definir os campos que serão incluídos no índice.

Nota: Para obter mais informações sobre como atualizar o esquema de uma ligação existente, veja Capacidades de atualização de esquemas.

Definições de ligação

Pode configurar as predefinições de ligação para cada experiência de conteúdo ativada. Quando ativadas, estas definições afetam as experiências de conteúdo.

Configurações de pesquisa

Pode definir a forma como os resultados da pesquisa são apresentados na página de resultados do Microsoft Search ao fornecer os modelos de apresentação de pesquisa predefinidos para o seu conteúdo em searchSettings. Um conjunto de modelos de apresentação de pesquisa pode ser utilizado para apresentar diferentes tipos de resultados de pesquisa. Um modelo de apresentação de pesquisa tem um esquema de resultados criado com Cartões Ajustáveis e regras que especificam uma ou mais condições. Quando estas condições são cumpridas, o esquema é aplicado ao resultado da pesquisa e apresentado na página de resultados.

Definições de atividade

Nas definições de atividade, pode fornecer uma forma de as aplicações do Microsoft 365 detetarem atividade de partilha, o que permite que os seus conteúdos sejam recomendados aos utilizadores que interagem mais com esse conteúdo. Para tal, adicione um urlToItemResolver. Isto permite que um URL da ligação detetada nas aplicações do Microsoft 365 seja resolvido para o respetivo ID de item no externalItem.

A imagem seguinte mostra como o item pode aparecer nas experiências de recomendação no Microsoft 365.

O exemplo seguinte mostra o payload activitySettings com uma secção completa urlToItemResolvers . Por exemplo, quando alguém partilha a ligação https://contoso.com/items/39483948/, representa um externalItem que foi ingerido através de uma ligação do Microsoft Graph. Neste exemplo, a ligação partilhada representa um externalItem com um itemId de id_39483948. Esta ligação especifica como mapear do URL para o itemId desse externalItem. Neste exemplo, esta ligação tem um ID de contosohr.

Atualize as definições de atividade ao enviar um pedido de patch na ligação.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

O payload activitySettings seguinte é enviado com o pedido de patch.

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

Neste exemplo, o campo itemId especificou como formar o ID do item externo que o URL representa. O itemId é referenciado no urlPattern (que está dentro de urlMatchInfo) para extrair 39483948 como o ID do externalItem.

Pode fornecer uma lista de até oito recursos itemIdResolver no recurso urlToItemResolvers para o payload das definições de atividade. Para cada um destes recursos urlMatchInfo , especifique um valor de #microsoft.graph.externalConnectors.itemIdResolver para o @odata.type, um número inteiro de um a oito para a propriedade de prioridade e um objeto urlMatchInfo que contém uma lista de URLs base e uma expressão regular.

Quando uma ligação é partilhada, os objetos urlMatchInfo que pertencem às resoluções são aplicados pela ordem que os valores de prioridade especificam. Por ordem de prioridade ascendente, o URL é primeiro comparado com os URLs na lista baseUrls na propriedade urlMatchInfo . Em seguida, se a base do URL da ligação estiver na lista baseUrls , a expressão regular urlPattern é aplicada ao URL. Se este padrão corresponder, não serão aplicadas mais resoluções. Se a base do URL da ligação não estiver na lista baseUrls ou o urlPattern não corresponder, o urlToItemResolver seguinte é avaliado até ser encontrada uma correspondência ou não existem mais recursos urltoItemResolver a aplicar.

Para saber mais sobre os recursos urlMatchInfo , veja o tipo urlMatchInfo.

Atualizar uma conexão

Para alterar o nome a apresentar, a descrição ou as experiências de conteúdo ativadas para uma ligação existente, pode atualizar a ligação.

Excluir uma conexão

Para remover todos os itens que foram indexados por meio de uma conexão, você pode excluir uma conexão.

Compartilhar via