Configurare una connessione esterna e distribuire lo schema

Completato

In questa unità si apprenderà come configurare una registrazione dell'app Microsoft Entra da usare con un connettore Graph personalizzato. Si apprenderà anche come creare una connessione esterna e configurare uno schema per l'importazione di contenuto esterno.

Configurare Microsoft Entra registrazione dell'app

Per importare contenuto esterno in Microsoft 365, un connettore Graph richiede una connessione esterna e uno schema. Un connettore Graph personalizzato usa le API di Microsoft Graph per creare la connessione esterna e distribuire lo schema. Per comunicare con le API Graph, esegue l'autenticazione con Microsoft 365 usando una registrazione dell'app Microsoft Entra. In genere, i connettori Graph sono app eseguite senza interazione dell'utente. Per consentire ai connettori di creare la connessione, distribuire lo schema e inserire contenuto esterno, concedere loro le autorizzazioni dell'applicazione seguenti:

• ExternalConnection.ReadWrite.OwnedBy , che consente al connettore di creare la connessione e distribuire lo schema,
• ExternalItem.ReadWrite.OwnedBy , che consente al connettore di inserire elementi esterni

Entrambe le autorizzazioni consentono al connettore di accedere solo alla connessione e agli elementi di cui è proprietario, ovvero la procedura di sicurezza consigliata.

Creare una connessione esterna

Un connettore Graph personalizzato crea una connessione esterna usando l'endpoint di Microsoft Graph per la connessione esterna. Quando si crea una connessione, è necessario specificarne l'ID, il nome e la descrizione. L'ID deve essere univoco nel tenant di Microsoft 365 e avere una lunghezza compresa tra 3 e 32 caratteri. Il frammento di codice seguente illustra come creare una connessione esterna:

using Microsoft.Graph.Models.ExternalConnectors;

var requestBody = new ExternalConnection
{
  Id = "msgraphdocs",
  Name = "Microsoft Graph documentation",
  Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.",
};

await graphClient.External.Connections.PostAsync(requestBody);

Distribuire lo schema

Dopo aver creato una connessione esterna, il passaggio successivo consiste nel distribuire lo schema. Lo schema è costituito da una o più proprietà. Per ogni proprietà, è necessario specificare il nome e il tipo di dati archiviati. È anche possibile definire se i relativi dati devono essere usati per la ricerca full-text e l'ordinamento. Infine, è possibile aggiungere una o più etichette semantici che consentono a Microsoft 365 di comprendere le informazioni che la proprietà rappresenta. Microsoft 365 Copilot richiede una connessione esterna per definire nello schema almeno il titolo, l'URL e l'iconaEtichette semantica dell'url. Il frammento di codice seguente illustra come distribuire uno schema:

using Microsoft.Graph.Models.ExternalConnectors;

var schema = new Schema
{
  BaseType = "microsoft.graph.externalItem",
  Properties = new()
  {
    new Property
    {
      Name = "title",
      Type = PropertyType.String,
      IsQueryable = true,
      IsSearchable = true,
      IsRetrievable = true,
      Labels = new() { Label.Title }
    },
    new Property
    {
      Name = "iconUrl",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.IconUrl }
    },
    new Property
    {
      Name = "url",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.Url }
    },
  }
};

await graphClient.External
  .Connections["{externalConnection-id}"]
  .Schema
  .PatchAsync(schema);

La distribuzione di uno schema di connessione esterna è un'operazione a esecuzione prolungata che richiede da 5 a 15 minuti. Per sapere quando il provisioning è terminato e la connessione è pronta per l'uso, recuperare le informazioni sulla connessione e controllarne lo stato. Se la connessione non è ancora pronta, attendere 1 minuto prima di controllarne di nuovo lo stato.

do {
  var externalConnection = await GraphService.Client.External
    .Connections["{externalConnection-id}"]
    .GetAsync();

  if (externalConnection?.State != ConnectionState.Draft)
  {
    break;
  }

  await Task.Delay(60_000);
}
while (true);