Esercizio - Configurare una connessione esterna e distribuire lo schema

8 minuti

In questo esercizio viene creato un connettore Microsoft Graph personalizzato come applicazione console. Si registra una nuova registrazione dell'app Microsoft Entra e si aggiunge il codice per creare una connessione esterna e distribuirne lo schema.

Creare un nuovo progetto connettore Graph

Per iniziare, creare un nuovo progetto di connettore Graph. Anche se è possibile creare manualmente il progetto e tutti i file necessari, in questo esempio si usa il repository GitHub modello per i connettori Graph. Il vantaggio dell'uso del repository di modelli è che crea automaticamente un progetto semplice con i file e le dipendenze necessari, risparmiando tempo.

In una riga di comando:

Clonare il repository di modelli eseguendo git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

Consiglio

Se Git non è installato o non si dispone di un account GitHub, è possibile scaricare il repository come file ZIP. Estrarre il file ZIP in una cartella del computer per continuare con l'esercizio.
Modificare la directory di lavoro nel repository clonato.
Aprire il progetto appena creato nell'editor di codice.

Nell'editor di codice:

Aprire il file ConnectionConfiguration.cs . Nell'oggetto restituito dal ExternalConnection getter:
1. Modificare il valore della proprietà Id in msgraphdocs.
2. Modificare il valore della proprietà Name in Microsoft Graph documentation.
3. Modificare il valore della proprietà Description in Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.
Salvare le modifiche.

Consiglio

Il README.md file nel progetto generato contiene altre informazioni sui diversi file e cartelle nel progetto. Prenditi un momento per leggerlo e acquisire familiarità con la struttura del progetto.

Registrare una nuova registrazione dell'app Microsoft Entra

Il progetto creato contiene uno script di installazione che crea e configura una nuova registrazione dell'app Microsoft Entra. Il connettore Graph usa questa registrazione dell'app per l'autenticazione con Microsoft 365.

In una riga di comando:

Modificare la directory di lavoro nella cartella del progetto.
Eseguire lo script di installazione: .\setup.ps1
Quando richiesto, accedere al tenant di Microsoft 365 con l'account aziendale.
Attendere che lo script termini la creazione della registrazione dell'app. Lo script crea una registrazione dell'app Entra denominata documentazione di Microsoft Graph.
Al termine, lo script archivia in modo sicuro le informazioni di registrazione dell'app nei segreti utente.

Lo script di installazione usa Microsoft Graph PowerShell SDK per creare una nuova registrazione dell'app Microsoft Entra nel tenant. Configura la registrazione dell'app con Microsoft API Graph autorizzazioni necessarie per creare una connessione esterna e inserire il contenuto. Configura anche la registrazione dell'app con un segreto per consentire l'autenticazione senza l'interazione dell'utente.

Consiglio

Per esplorare la configurazione di registrazione dell'app, in un Web browser:

Passare al portale di Azure all'indirizzo https://portal.azure.com.
Nel riquadro di spostamento selezionare Microsoft Entra ID.
Nel riquadro di spostamento laterale selezionare Registrazioni app.
Nell'elenco delle registrazioni dell'app selezionare la registrazione dell'app creata dallo script di installazione.
Esplorare le diverse proprietà, ad esempio autorizzazioni API, certificati & segreti e autenticazione.

Definire la connessione esterna e la configurazione dello schema

Il passaggio successivo consiste nel definire la connessione esterna e lo schema che il connettore Graph deve usare. Poiché il codice del connettore deve accedere all'ID della connessione esterna in diverse posizioni, archiviarlo in una posizione centrale nel codice.

Nell'editor di codice:

Aprire il file ConnectionConfiguration.cs .
Dall'oggetto restituito dalla ExternalConnection proprietà rimuovere le ActivitySettings proprietà e SearchSettings . Non sono necessari per questo esercizio.
Si noti che le proprietà dello schema restituite dalla Schema proprietà .

La prima proprietà è title, che archivia il titolo dell'elemento esterno importato in Microsoft 365. Il titolo dell'elemento fa parte dell'indice full-text (IsSearchable = true). Gli utenti possono anche eseguire query esplicite sul contenuto nelle query con parole chiave (IsQueryable = true). Il titolo può essere anche recuperato e visualizzato nei risultati della ricerca (IsRetrievable = true). La title proprietà rappresenta il titolo dell'elemento, che viene indicato usando l'etichetta Title semantica.

Successivamente, è disponibile la url proprietà , che archivia l'URL originale dell'elemento esterno. Gli utenti usano questo URL per passare all'elemento esterno dai risultati della ricerca o a Copilot da Microsoft 365. L'URL è una delle proprietà richieste Microsoft 365 Copilot, motivo per cui viene eseguito il mapping usando l'etichetta Url semantica.

Infine, c'è la iconUrl proprietà che archivia l'URL dell'icona per ogni elemento. Microsoft 365 Copilot richiede questa proprietà e deve essere mappata usando l'etichetta IconUrl semantica.

Microsoft 365 Copilot richiede che i connettori Graph definiscano almeno queste tre proprietà e le designino con le etichette semantiche appropriate.
Properties Alla matrice aggiungere una nuova proprietà denominata description:
```
new Property
{
  Name = "description",
  Type = PropertyType.String,
  IsQueryable = true,
  IsSearchable = true,
  IsRetrievable = true
}
```
La description proprietà archivia il riepilogo del contenuto dell'elemento esterno. La sua definizione è simile al titolo. Non esiste tuttavia alcuna etichetta semantica per la descrizione, motivo per cui non viene definita.

Il codice completo è simile al seguente:

using System.Text.Json;
using Microsoft.Graph.Models;
using Microsoft.Graph.Models.ExternalConnectors;

static class ConnectionConfiguration
{
  private static Dictionary<string, object>? _layout;
  private static Dictionary<string, object> Layout
  {
    get
    {
      if (_layout is null)
      {
        var adaptiveCard = File.ReadAllText("resultLayout.json");
        _layout = JsonSerializer.Deserialize<Dictionary<string, object>>(adaptiveCard);
      }

      return _layout!;
    }
  }

  public static ExternalConnection ExternalConnection
  {
    get
    {
      return 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."
      };
    }
  }

  public static Schema Schema
  {
    get
    {
      return 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 = "url",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.Url }
          },
          new Property
          {
            Name = "iconUrl",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.IconUrl }
          },
          new Property
          {
            Name = "description",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true
          }
        }
      };
    }
  }
}

Save your changes

Esaminare il codice di creazione della connessione

Il generatore di progetti del connettore Graph crea codice che crea la connessione esterna ed esegue il provisioning del relativo schema. È possibile usarlo senza alcuna modifica. Prima di procedere, esaminarlo per capire come funziona. Il codice si trova nel file ConnectionService.cs .

Nell'editor di codice:

Aprire il file ConnectionService.cs .
Il file contiene due metodi: CreateConnection e CreateSchema. Il CreateConnection metodo crea la connessione esterna e il metodo esegue il CreateSchema provisioning dello schema.

Se si ricorda, il provisioning dello schema di connessione esterna è un'operazione a esecuzione prolungata. Il codice nel CreateSchema metodo, tuttavia, non sembra attendere il provisioning dello schema. Il client Microsoft Graph in questo progetto usa un middleware personalizzato che attende il completamento dell'operazione. Poiché questo middleware gestisce l'attesa del completamento dell'operazione, la CreateSchema funzione non deve includere altro codice e deve solo attendere la richiesta API. Il middleware si trova nel file CompleteJobWithDelayHandler.cs .

Eseguire il test del codice

L'ultimo passaggio a sinistra consiste nel verificare che il codice funzioni correttamente. Il file Program.cs contiene il punto di ingresso per l'applicazione. Usa il pacchetto System.CommandLine per definire un comando richiamato avviando l'applicazione dalla riga di comando.

In una riga di comando:

Aprire una finestra terminale.
Modificare la directory di lavoro nella cartella del progetto.
Eseguire dotnet build per compilare il progetto.
Avviare l'app eseguendo dotnet run -- create-connection.
Attendere alcuni minuti per la creazione della connessione e dello schema.

Esercizio - Configurare una connessione esterna e distribuire lo schema

Creare un nuovo progetto connettore Graph

Registrare una nuova registrazione dell'app Microsoft Entra

Definire la connessione esterna e la configurazione dello schema

Esaminare il codice di creazione della connessione

Eseguire il test del codice

Commenti e suggerimenti