Поделиться через

Руководство по началу работы с агентом SharePoint Embedded

Предварительные требования

Примечание.

  1. Вам потребуется создать приложение SharePoint Embedded. Если у вас его нет, вы можете легко создать пример приложения, выполнив инструкции здесь.
  2. Во время создания необходимо указать стандартный тип контейнера. В зависимости от цели может потребоваться указывать идентификатор подписки Azure. Тип контейнера, заданный для пробных целей, нельзя преобразовать в рабочую среду или наоборот.
  3. Для настройки типа контейнера необходимо использовать последнюю версию SharePoint PowerShell. Разрешения и самые актуальные сведения о Windows PowerShell для SharePoint Embedded см. в документации по статье Введение в SharePoint Embedded Management Shell.

Начало работы с пакетом SDK для SharePoint Embedded

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. Создайте состояние React для хранения в chatApi

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. Добавьте компонент в ChatEmbedded приложение 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. Используйте 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. Чат ИИ должен быть загружен успешно

Начало работы с расширением SharePoint Embedded Visual Studio Code

Краткая инструкция

Примечание.

При использовании стандартных типов контейнеров с расширением VS Code функции DisableDiscoverability и Grant admin consent в настоящее время не поддерживаются. Это необходимо сделать с помощью SPO Администратор PowerShell.

  1. Следуйте этому руководству в разделе Загрузка примера приложения с расширением Visual Studio Code

  2. В расширении щелкните правой кнопкой мыши владеющее приложение и выберите Run sample apps -> Typescript + React + Azure Functions

    Использование расширения SPE VS Code для создания проекта typeScript React Функции Azure

  3. Разрешить расширению копировать и создавать секреты клиента

    Предостережение

    Внимание, что в рабочих средах хранение секретов в виде обычного текста представляет угрозу безопасности.

    Уведомление SPE VS Code с оповещением о копировании секретов приложения в виде обычного текста на локальном компьютере

    Если у приложения еще нет секрета клиента, расширение попросит создать его за вас.

    Уведомление SPE VS Code с предложением разрешить пользователю создать секрет для приложения, если он не существует.

  4. Выберите папку для размещения приложения. Следующий репозиторий для примеров SharePoint Embedded будет клонировать в папку

    windows проводник папку для сохранения проекта на локальном компьютере

    Затем при появлении запроса откройте папку

    Расширение VS Code с spe React Typescript + Функции Azure пример приложения, клонированного на локальном компьютере и открытого в VS Code

  5. Перейдите к разделу react-client\src\components\ChatSideBar.tsx и раскомментируйте его

    Обозреватель файлов VS Code с ChatSideBar.tsx в открытом окне с выделенным соответствующим кодом для раскомментирования

  6. Перейдите к react-client\src\routes\App.tsx и задайте для React состояние переменной showSidebar значение .true

    Обозреватель файлов VS Code с открытым app.tsx со строкой showSidebar переменной useState вводимые данные функции изменились с false на true, чтобы включить отображение боковой панели чата

  7. Вы можете следовать инструкциям README.md файла в корневой папке проекта для дальнейших команд npm. Запустите npm run start в корне проекта, чтобы запустить приложение с включенными функциями агента SPE.

    Примечание.

    npm run start Должно быть выполнено в корневой папке примера проекта. \SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction

    Терминал VS Code в корневой папке проекта SPE Typescript, клонированного ранее, и npm выполните команду start, введенную в

  8. Войдите с пользователем, у которого включена лицензия на Microsoft 365 Copilot.

    Приложение SPE Typescript, работающее в Edge с кнопками входа

  9. Перейдите на страницу containers и создайте ее, если у вас еще нет

    Приложение SPE Typescript, работающее на пограничной странице /containers с модальным пользователем c повторной настройкой контейнера ContosoCompanyContainer

    После создания вы увидите его здесь:

    Приложение SPE Typescript, работающее в edge с созданным контейнером из выше ContosoCompanyContainer

  10. Щелкните контейнер и отправьте файлы. После создания контейнера и перехода в него взаимодействие с чатом агента станет включенным.

    Приложение SPE Typescript, работающее в edge на странице созданного контейнера ContosoCompanyContainer

Примеры

В репозитории Примеры SharePoint Embedded приведены примеры использования SharePoint Embedded в пользовательских приложениях.

  • Last updated on