SharePoint Embedded エージェントの使用を開始するためのチュートリアル

2025-06-13

前提条件

注:

SharePoint Embedded アプリケーションを作成する必要があります。お持ちでない場合は、こちらの手順を使用してサンプルアプリケーションを簡単にビルドできます。
作成時に標準コンテナーの種類を指定する必要があります。目的によっては、Azure サブスクリプション ID を指定する必要がある場合と必要ない場合があります。試用版用に設定されたコンテナーの種類は、運用環境用に変換することも、その逆に変換することもできません。
コンテナーの種類を構成するには、最新バージョンの SharePoint PowerShell を使用する必要があります。 SharePoint Embedded のWindows PowerShellに関するアクセス許可と最新の情報については、「SharePoint Embedded Management Shell の概要」のドキュメントを参照してください。

コンテナーの種類の構成の CopilotChatEmbeddedHosts プロパティを http://localhost:8080 に設定して、以下のクイックスタートを実行できるようにするには、上記の CSP セクションを参照してください。
エージェントが作成したコンテナー内のファイルを検索できるように、コンテナーの種類の構成の DiscoverabilityDisabled プロパティを false に設定します。詳細については、上記の「検出可能性が無効」セクションを参照してください。
Organizationで Copilot for Microsoft 365 を使用できることを確認します。 Copilot の開発環境を取得するには、次の 2 つの方法があります。
- M365 Copilot を含むサンドボックス Microsoft 365 テナント ( TAP メンバーシップを通じて限定プレビューで利用できます)。
  - M365 Copilot ライセンスを持つ適格な Microsoft 365 またはOffice 365運用環境。

SharePoint Embedded SDK の使用の概要

1. SDK を 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"

チェックサムを確認する場合

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; }

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. `authProvider` オブジェクトを作成する

これは、このインターフェイスに一致するオブジェクトです。

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>;
}

アプリでの使用例:

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

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

getTokenの実装例 (カスタマイズする必要があります)。

//
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. `chatApi`を格納するReact状態を作成する

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

例:

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. react アプリに `ChatEmbedded` コンポーネントを追加する

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. 状態の `chatApi` オブジェクトを使用してチャットを開き、実行します

上の例では、この方法で呼び出してチャットを開きます。

await chatApi.openChat();

起動構成を渡すことができます

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);

完全な例:

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. AI チャットが正常に読み込まれる必要がある

SharePoint Embedded Visual Studio Code 拡張機能の使用の概要

クイックスタート

注:

VS Code 拡張機能で標準のコンテナーの種類を使用する場合、 DisableDiscoverability と Grant admin consent 機能は現在サポートされていません。これは、Powershell 管理 SPO を使用して行う必要があります。

Visual Studio Code 拡張機能を使用したサンプルアプリの読み込みセクションまで、このガイドに従ってください
拡張機能内で、所有しているアプリケーションを右クリックし、 Run sample apps -> Typescript + React + Azure Functions
拡張機能でクライアントシークレットのコピーと作成を許可する

注意

運用環境では、シークレットをプレーンテキストで格納するとセキュリティ上のリスクが生じます。

アプリケーションにクライアントシークレットがまだない場合、拡張機能はクライアントシークレットの作成を求められます。
アプリケーションをホストするフォルダーを選択すると、 SharePoint Embedded Samples の次のリポジトリがフォルダーに複製されます

次に、メッセージが表示されたら、フォルダーを開きます
react-client\src\components\ChatSideBar.tsxに移動し、このセクションのコメントを解除します
react-client\src\routes\App.tsxに移動し、showSidebar変数のReact状態をに設定しますtrue
さらに npm コマンドを実行するには、プロジェクトのルートにある README.md ファイルの指示に従います。プロジェクトのルートで npm run start を実行して、SPE エージェント機能を有効にしてアプリケーションを起動します。

注:

npm run start サンプルプロジェクトのルートフォルダーで実行する必要があります。 \SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction
Microsoft 365 Copilot ライセンスが有効になっているユーザーでサインインします。
containers ページに移動し、まだ作成していない場合は作成します

作成後、ここに表示されます。
コンテナーをクリックし、ファイルをアップロードします。コンテナーが作成され、コンテナー内を移動すると、エージェントチャットエクスペリエンスが有効になります。