Criar conectores do Microsoft 365 Copilot para dados de pessoas

Os conectores do Microsoft 365 Copilot para dados de pessoas permitem que você insira dados de pessoas e conhecimento de seus sistemas de origem (por exemplo, recursos humanos, gerenciamento de talentos ou outros sistemas de pessoas) no Microsoft Graph. Adicionar dados de pessoas ao Microsoft Graph os disponibiliza para o Microsoft 365 Copilot e experiências de pessoas, como o cartão de perfil e a pesquisa de pessoas. Quando você ingere seus dados, o Copilot pode raciocinar sobre os dados e usá-los para responder às perguntas dos usuários.

Você cria conectores do Microsoft 365 Copilot para dados de pessoas da mesma forma que cria outros conectores do Copilot, usando as APIs de conexões externas do Microsoft Graph. Para garantir que o Microsoft 365 reconheça que sua conexão contém dados de pessoas, siga os requisitos de configuração e esquema de conexão e registre a conexão como uma fonte de dados de perfil.

Observação

Para obter um exemplo de um conector que fornece dados de pessoas, consulte Conector do Microsoft 365 Copilot para exemplo de dados de pessoas.

Requisitos de configuração de conexão

Os conectores do Copilot que contêm dados de pessoas devem ter o valor people na contentCategory propriedade da externalConnections API.

Requisitos de esquema de conexão

Os conectores do Microsoft 365 Copilot para pessoas Enriquecimento de dados para as seguintes entidades de perfil de usuário do Microsoft 365.

  • O esquema deve ter uma propriedade com o personAccount rótulo para poder mapear o externalItem para uma pessoa.
  • As propriedades sem um rótulo são consideradas propriedades personalizadas.
Rótulo da propriedade Tipo de propriedade Entidade de perfil Descrição
personAccount string userAccountInformation Indica o usuário do Microsoft Entra ID que o item destina.
personCurrentPosition string workPosition Descreve a posição atual da pessoa.
personAddresses stringCollection itemAddress Máximo de 3, um de Homecada e WorkOther. Adiciona endereços ao usuário.
personAnniversaries stringCollection personAnniversary Adiciona um ou mais aniversários à pessoa.
personAwards stringCollection personAward Descreve os prêmios que o usuário ganhou.
personCertifications stringCollection personCertification Descreve as certificações que o usuário obteve.
personEducationalActivities stringCollection educationalActivity Descreve as atividades educacionais do usuário.
personEmails stringCollection itemEmail Máximo 3. Adiciona endereços de email ao usuário.
personInterests stringCollection personInterest Informações detalhadas sobre os interesses do usuário.
personLanguages stringCollection languageProficiency Informações detalhadas sobre os idiomas que o usuário conhece.
personName string personName Adiciona nomes ao usuário.
personNote string personAnnotation Acrescenta uma nota ao usuário.
personPatents stringCollection itemPatent Descreve uma patente concedida ou registrada à qual o usuário está associado.
personPhones stringCollection itemPhone Adiciona números de telefone ao usuário.
personPublications stringCollection itemPublication Descreve publicações ou artigos aos quais o usuário está associado.
personProjects stringCollection projectParticipation Descreve os projetos dos quais o usuário participou.
personSkills stringCollection skillProficiency Descreve as habilidades nas quais o usuário é proficiente.
personWebAccounts stringCollection webAccount Descreve as contas da Web externas que o usuário tem.
personWebSite string webSite Descreve um site para o usuário.
personWorkPositions stringCollection workPosition Descreve as posições de trabalho históricas do usuário.

Exemplo de esquema:

{
  "baseType": "microsoft.graph.externalItem",
  "properties": [
    {
      "name": "accountInformation",
      "type": "string",
      "labels": ["personAccount"]
    },
    {
      "name": "position",
      "type": "string",
      "labels": ["personCurrentPosition"]
    },
    {
      "name": "skills",
      "type": "stringCollection",
      "labels": ["personSkills"]
    },
    {
      "name": "requisitionId",
      "type": "string",
      "description": "The user's requisition ID"
    }
  ]
}

Serialização de entidades JSON

Cada propriedade, com um rótulo, é do tipo string ou stringCollection, e é uma representação de cadeia de caracteres serializada em JSON da entidade de perfil do Microsoft 365 a ser enriquecida.

{
  ...
  "properties": {
    "accountInformation": "{\"userPrincipalName\": \"adelev@contoso.com\"}",
    "position": "{\"detail\":{\"jobTitle\":\"ProductManager\"}}",
    "skills@odata.type": "Collection(String)",
    "skills": [
      "{\"displayName\":\"Product requirements\"}",
      "{\"displayName\":\"Customer research\"}"
    ],
    "requisitionId": "REQ-12345678"
  }
}

Registrar a conexão como uma fonte de perfil

Depois de criar a conexão, registre-a como uma fonte de dados de perfil e adicione-a à lista de fontes priorizadas.

Registre a conexão como uma fonte de perfil usando a API de origem de perfil definida sourceId como a ID de conexão do conector e a webUrl propriedade definida como um link HTTPS para o sistema externo ou uma página com informações adicionais sobre a origem.

Após o registro, adicione a conexão à lista de fontes de perfil priorizadas usando a API de configurações de propriedade do perfil. Adicione a URL à origem do perfil, no formato de https://graph.microsoft.com/v1.0/admin/people/profileSources(sourceId='connectionId'), onde connectionId está a ID de conexão exclusiva da conexão, à prioritizedSourceUrls matriz. Essa matriz representa a ordem na qual o Microsoft 365 compõe o modo de exibição de uma pessoa. Se você quiser que sua conexão seja a fonte de prioridade mais alta, adicione-a como o primeiro item na matriz.

Recomendações para conectores de pessoas

A seguir estão diretrizes e recomendações para conectores do Copilot com dados de pessoas, para melhorar o raciocínio e a qualidade no chat do Microsoft 365 Copilot e na Pesquisa do Copilot:

  • Reutilize o máximo possível das propriedades disponíveis nas entidades de perfil, definidas pelos rótulos, em vez de criar uma propriedade personalizada.
  • Para propriedades personalizadas, use um nome de propriedade que os usuários e agentes entendam. Por exemplo, use requisitionId em vez de reqId.
  • Ao definir o esquema, forneça um legível description para cada propriedade personalizada. As descrições em propriedades com person* rótulos são ignoradas.
  • Para propriedades personalizadas complexas, use texto livre, Markdown ou YAML em vez de JSON.

Notas e limitações

  • Os dados de pessoas fornecidos por meio de um conector do Copilot são visíveis para todos os usuários na organização. Os dados do conector são armazenados no perfil do Microsoft 365 do usuário. Para obter mais informações, consulte Conectores do Microsoft 365 Copilot para dados de pessoas.
  • Você deve definir a ACL (lista de controle de acesso) nos itens ingeridos pelo conector para conceder acesso a todos.
  • Você deve fornecer objetos JSON codificados em cadeia de caracteres válidos para entidades de perfil. O Microsoft Graph ignora valores inválidos.
  • Contas de usuário não correspondentes (userPrincipalName ou externalDirectoryObjectId) são ignoradas.
  • O Microsoft Graph ignora contas sem uma caixa de correio do Exchange Online.
  • O Microsoft Graph trata qualquer propriedade sem um rótulo como uma propriedade personalizada.
  • O Microsoft 365 pode levar até 6 horas após a conexão ser criada para ficar disponível na pesquisa, nas experiências de pessoas ou no Copilot.
  • As conexões com dados de pessoas não dão suporte a conexões em estágios.
  • No momento, não há suporte para os seguintes rótulos: personManager, personAssistants, personAlternateContactspersonColleagues, e personEmergencyContacts.
  • No momento, não há suporte para os tipos de propriedade de esquema e principalCollection conector principal do Copilot. Use a colleagues coleção da workPosition entidade para criar relações.
  • Os seguintes atributos de esquema do conector do Copilot são ignorados: isQueryable, isRefinable, isRetrievable, isSearchable. Todos os dados sobre uma pessoa são indexados por padrão.