Lire en anglais

Partager via

Tutoriel pour la prise en main du copilote SharePoint Embedded

  • Article

Conditions préalables

Notes

  1. Vous devez créer une application SharePoint Embedded. Si vous n’en avez pas, vous pouvez facilement créer un exemple d’application en suivant les instructions fournies ici.
  2. Vous devez spécifier un type de conteneur standard au moment de la création. Selon l’objectif, vous devrez peut-être fournir ou non votre ID d’abonnement Azure. Un type de conteneur défini à des fins d’évaluation ne peut pas être converti pour la production . ou vice versa.
  3. Vous devez utiliser la dernière version de SharePoint PowerShell pour configurer un type de conteneur. Pour obtenir les autorisations et les informations les plus actuelles sur Windows PowerShell pour SharePoint Embedded, consultez la documentation de la page Présentation de SharePoint Embedded Management Shell.

Prise en main du Kit de développement logiciel (SDK) SharePoint Embedded

1. Installer le Kit de développement logiciel (SDK) dans votre dépôt React

# Install the SDK with npm

npm install "https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz"

Si vous souhaitez vérifier les sommes de contrôle

Dans MacOS/Linux

version="1.0.7";

url="https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz"; 

expected_checksum="A87FF410E8684A3C16456B2092564422BF80DA9FAFF3A684821DACEAEEA23D22"; 

package_path="microsoft-sharepointembedded-copilotchat-react-$version.tgz"; 

curl -o $package_path $url && [ "$(sha256sum $package_path | awk '{ print $1 }')" == "$expected_checksum" ] && npm install $package_path || { echo "Checksum does not match. Aborting installation."; rm $package_path; }

Dans Windows :

$version = "1.0.7"
$url = "https://download.microsoft.com/download/27d10531-b158-40c9-a146-af376c0e7f2a/microsoft-sharepointembedded-copilotchat-react-1.0.7.tgz"
$expected_checksum = "A87FF410E8684A3C16456B2092564422BF80DA9FAFF3A684821DACEAEEA23D22"
$package_path = "microsoft-sharepointembedded-copilotchat-react-$version.tgz"

Invoke-WebRequest -Uri $url -OutFile $package_path

$calculated_checksum = Get-FileHash -Path $package_path -Algorithm SHA256 | Select-Object -ExpandProperty Hash

if ($calculated_checksum -eq $expected_checksum) {
    Write-Output "Checksum matches. Installing the package..."
    npm install $package_path
} else {
    Write-Output "Checksum does not match. Aborting installation."
}
Remove-Item $package_path

2. Créer un authProvider objet

Il s’agit d’un objet qui correspond à cette interface :

export interface IChatEmbeddedApiAuthProvider {
    // The hostname for your tenant. Example: https://m365x10735106.sharepoint.com
    hostname: string;
    // This function will be called when an SPO token is required
    // Scope needed: ${hostname}/Container.Selected
    getToken(): Promise<string>;
}

Exemple d’utilisation dans l’application :

// In your app:
import { IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react';

const authProvider: IChatEmbeddedApiAuthProvider = {
    hostname: 'https://m365x10735106.sharepoint.com',
    getToken: requestSPOAccessToken,
};

Exemple d’implémentation de getToken (vous devez la personnaliser) :

//
async function requestSPOAccessToken() {
  // Use your app's actual msalConfig
  const msalConfig = {
    auth: {
      clientId: "{Your Entra client ID}", // this can likely point to process.env.REACT_APP_CLIENT_ID if you have set it in your .env file
    },
    cache: {
              // https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/caching.md
              /*
              Cache Location | Cleared on | Shared between windows/tabs | Redirect flow supported
              -----------------   ----------  -------------------------   ------------------------
              sessionStorage | window/tab close | No | Yes
              localStorage | browser close | Yes |   Yes
              memoryStorage | page |  refresh/navigation | No | No
              */
      cacheLocation: 'localStorage',
      storeAuthStateInCookie: false,
    },
  };

  const containerScopes = {
    scopes: [`${authProvider.hostname}/Container.Selected`],
    redirectUri: '/'
  };

  const pca = new msal.PublicClientApplication(msalConfig);
  let containerTokenResponse;

  // Consent FileStorageContainer.Selected scope
  try {
    // attempt silent acquisition first
    containerTokenResponse = await pca.acquireTokenSilent(containerScopes);
    return containerTokenResponse.accessToken;
  } catch (error) {
    if (error instanceof InteractionRequiredAuthError) {
      // fallback to interaction when silent call fails
      containerTokenResponse = await pca.acquireTokenPopup(containerScopes);
      return containerTokenResponse.accessToken;
    }
    else {
      console.log(error);
    }
  }
}

3. Créer un état React pour stocker votre chatApi dans

const [chatApi, setChatApi] = React.useState<ChatEmbeddedAPI|null>(null);

Exemple :

import React from 'react';
import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react';

//...
async function requestSPOAccessToken() {
  //...
}

const authProvider: IChatEmbeddedApiAuthProvider = {
  hostname: 'https://m365x10735106.sharepoint.com',
  getToken: requestSPOAccessToken,
};

function App() {
  const [chatApi, setChatApi] = React.useState<ChatEmbeddedAPI|null>(null);

  return (
    //...
  );
}

4. Ajouter le ChatEmbedded composant à votre application React

import React from 'react';
import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react';

//...
async function requestSPOAccessToken() {
  //...
}

const authProvider: IChatEmbeddedApiAuthProvider = {
  hostname: 'https://m365x10735106.sharepoint.com',
  getToken: requestSPOAccessToken,
};

function App() {
  const [chatApi, setChatApi] = React.useState<ChatEmbeddedAPI|null>(null);

  return (
    //...
    <ChatEmbedded
      onApiReady={setChatApi}
      authProvider={authProvider}
      containerId={container.id}
      style={{ width: 'calc(100% - 4px)', height: 'calc(100vh - 8px)' }}
    />
    //...
  );
}

5. Utilisez l’objet chatApi dans votre état pour ouvrir la conversation et l’exécuter

Dans l’exemple ci-dessus, appelez-le de cette façon pour ouvrir la conversation.

await chatApi.openChat();

Vous pouvez choisir de transmettre des configurations de lancement

import { IconName, IconStyle } from './sdk/types';

//...
const zeroQueryPrompts = {
  headerText: "This is my Starter Prompt",
  promptSuggestionList: [{
    suggestionText: 'Hello',
    iconRegular: { name: IconName.ChatBubblesQuestion, style: IconStyle.Regular },
    iconHover: { name: IconName.ChatBubblesQuestion, style: IconStyle.Filled },
  }]
};

const launchConfig: ChatLaunchConfig = {
  header: 'My Awesome Chat',
  zeroQueryPrompts,
  suggestedPrompts: ["What are my files?",],
  instruction: "Response must be in the tone of a pirate",
  locale: "en",
};

await chatApi.openChat(launchConfig);

Exemple complet :

import React from 'react';
import { ChatEmbedded, ChatEmbeddedAPI, IChatEmbeddedApiAuthProvider } from '@microsoft/sharepointembedded-copilotchat-react';

//...
async function requestSPOAccessToken() {
  //...
}

const authProvider: IChatEmbeddedApiAuthProvider = {
  hostname: 'https://m365x10735106.sharepoint.com',
  getToken: requestSPOAccessToken,
};

function App() {
  const [chatApi, setChatApi] = React.useState<ChatEmbeddedAPI|null>(null);

  React.useEffect(() => {
    const openChat = async () => {
      if (!chatApi) {
        return;
      }

      await chatApi.openChat();
    };

    openChat();
  }, [chatApi]);


  return (
    //...
    <ChatEmbedded
      onApiReady={(api) => setChatApi(api)}
      authProvider={authProvider}
      containerId={container.id}
      style={{ width: 'calc(100% - 4px)', height: 'calc(100vh - 8px)' }}
    />
    //...
  );
}

6. Votre conversation IA doit être chargée avec succès

Prise en main de l’extension SharePoint Embedded Visual Studio Code

Démarrage rapide

Notes

Lorsque vous utilisez des types de conteneur standard avec l’extension VS Code, les fonctionnalités DisableDiscoverability et Accorder le consentement administrateur ne sont actuellement pas prises en charge. Cette opération doit être effectuée à l’aide du SPO Administration PowerShell.

  1. Suivez ce guide jusqu’à la section Charger l’exemple d’application avec l’extension Visual Studio Code

  2. Dans l’extension, cliquez avec le bouton droit sur l’application propriétaire, puis sélectionnez Run sample apps -> Typescript + React + Azure Functions

    Utilisation de l’extension VS Code SPE pour créer un projet TypeScript React Azure Functions

  3. Autoriser la copie et la création de secrets client par l’extension

    Attention

    Attention pour les environnements de production, le stockage de secrets en texte brut présente un risque pour la sécurité.

    Notification VS Code SPE signalant qu’il copiera les secrets de l’application en texte brut sur l’ordinateur local

    Si l’application n’a pas encore de clé secrète client, l’extension vous demande d’en créer une pour vous.

    Notification VS Code SPE invitant l’utilisateur à lui autoriser à créer un secret pour l’application s’il n’existe pas.

  4. Sélectionnez un dossier pour héberger l’application, ce qui clone le référentiel suivant pour les exemples SharePoint Embedded dans le dossier

    dossier windows Explorateur de fichiers pour enregistrer le projet sur l’ordinateur local

    Ensuite, lorsque vous y êtes invité, ouvrez le dossier

    Extension VS Code avec l’exemple d’application SPE React Typescript + Azure Functions cloné sur l’ordinateur local et ouvert dans VS Code

  5. Accédez à react-client\src\components\ChatSideBar.tsx cette section et supprimez les marques de commentaire

    Explorateur de fichiers VS Code avec ChatSideBar.tsx dans la fenêtre ouverte avec le code pertinent pour supprimer les marques de commentaire mis en évidence

  6. Accédez à react-client\src\routes\App.tsx et définissez l’état react de la variable showSidebar sur true

    Explorateur de fichiers VS Code avec App.tsx ouvert avec la ligne de la variable showSidebar useState entrée de la fonction false à true pour activer l’affichage de la barre latérale de conversation

  7. Vous pouvez suivre les instructions du README.md fichier à la racine du projet pour d’autres commandes npm. Exécutez npm run start à la racine du projet pour démarrer votre application avec la fonctionnalité de copilote SPE activée.

    Notes

    npm run start Doit être effectué dans le dossier racine de l’exemple de projet. \SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction

    Terminal VS Code dans le dossier racine du projet Typescript SPE cloné précédemment et la commande npm run start tapée dans

  8. Connectez-vous avec un utilisateur pour lequel une licence Copilot M365 est activée.

    Spe Typescript Application s’exécutant dans Edge avec des boutons de connexion

  9. Accédez à la containers page, créez-en une si vous n’en avez pas encore

    Spe Typescript Application s’exécutant dans edge dans la sous-page /containers avec modal de l’utilisateur c réatignez un conteneur appelé ContosoCompanyContainer

    Une fois qu’il a été créé, vous le verrez ici :

    Spe Typescript Application s’exécutant dans edge avec un conteneur créé au-dessus de ContosoCompanyContainer

  10. Cliquez sur le conteneur et chargez vos fichiers. Une fois qu’un conteneur a été créé et que vous y avez accédé, votre expérience de conversation copilote est activée.

    Spe Typescript Application s’exécutant dans edge à l’intérieur d’une page de conteneur créée de ContosoCompanyContainer

Exemples

Le référentiel Exemples SharePoint Embedded contient des exemples d’utilisation de SharePoint Embedded dans vos applications personnalisées.