Tutoriel pour bien démarrer avec l’agent SharePoint Embedded

Conditions préalables

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/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz"

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

Dans MacOS/Linux

version="1.0.9";

url="https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz"; 

expected_checksum="3bdf19830ffc098b253cc809f969f50fba236ad95fe85123e7b15c7cf58ecf6b"; 

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.9"
$url = "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz"
$expected_checksum = "3BDF19830FFC098B253CC809F969F50FBA236AD95FE85123E7B15C7CF58ECF6B"
$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

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

   

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é.

   

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

   

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

   

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

   

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

   

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

   

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 l’agent SPE activée.

   Remarque

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

   

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

   

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

   

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

   

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 d’agent est activée.

    

Exemples

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