Compartir a través de

Tutorial para empezar a trabajar con el agente de SharePoint Embedded

Requisitos previos

Nota:

  1. Tendrá que crear una aplicación de SharePoint Embedded. Si no tiene una, puede crear fácilmente una aplicación de ejemplo mediante las instrucciones que se indican aquí.
  2. Debe especificar un tipo de contenedor estándar en el momento de la creación. En función del propósito, puede que tenga que proporcionar o no el identificador de suscripción de Azure. Un conjunto de tipos de contenedor con fines de prueba no se puede convertir para producción ni viceversa.
  3. Debe usar la versión más reciente de SharePoint PowerShell para configurar un tipo de contenedor. Para obtener permisos y la información más reciente sobre Windows PowerShell para SharePoint Embedded, consulte la documentación de Intro to SharePoint Embedded Management Shell (Introducción al shell de administración de SharePoint Embedded).

Introducción al uso del SDK de SharePoint Embedded

1. Instale el SDK en el repositorio de 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 desea comprobar las sumas de comprobación

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

En 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. Crear un authProvider objeto

Se trata de un objeto que coincide con esta interfaz:

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

Ejemplo de uso en la aplicación:

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

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

Implementación de ejemplo de getToken (debe personalizarla):

//
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. Cree un estado de React para almacenar en chatApi

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

Ejemplo:

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. Agregar el componente a la ChatEmbedded aplicación 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. Use el chatApi objeto en su estado para abrir el chat y ejecutarlo.

En el ejemplo anterior, llámalo de esta manera para abrir el chat.

await chatApi.openChat();

Puede optar por pasar las configuraciones de inicio

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

Ejemplo completo:

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. El chat de IA debe cargarse correctamente

Introducción al uso de la extensión de Visual Studio Code de SharePoint Embedded

Inicio rápido

Nota:

Al usar tipos de contenedor estándar con la extensión VS Code, las características DisableDiscoverability y Grant admin consent no se admiten actualmente. Esto tendrá que realizarse mediante el SPO Administración PowerShell.

  1. Siga esta guía hasta la sección Cargar aplicación de ejemplo con la extensión Visual Studio Code

  2. Dentro de la extensión, haga clic con el botón derecho en la aplicación propietaria y seleccione Run sample apps -> Typescript + React + Azure Functions

    Uso de la extensión SPE VS Code para crear un proyecto de React Azure Functions TypeScript

  3. Permitir que la extensión copie y cree secretos de cliente

    Precaución

    Tenga cuidado con los entornos de producción, el almacenamiento de secretos en texto sin formato supone un riesgo de seguridad.

    Notificación DE VS Code de SPE que alerta de que copiará los secretos de la aplicación en texto sin formato en el equipo local

    Si la aplicación aún no tiene un secreto de cliente, la extensión le pedirá que cree uno automáticamente.

    Notificación DE VS Code de SPE que solicita al usuario que le permita crear un secreto para la aplicación si no existe.

  4. Seleccione una carpeta para hospedar la aplicación; esto clonará el siguiente repositorio para ejemplos incrustados de SharePoint en la carpeta .

    windows Explorador de archivos carpeta para guardar el proyecto en la máquina local

    A continuación, cuando se le solicite, abra la carpeta

    Extensión de VS Code con la aplicación de ejemplo typescript + Azure Functions spe React clonada en el equipo local y abierta en VS Code

  5. Vaya a react-client\src\components\ChatSideBar.tsx esta sección y quite la marca de comentario.

    Explorador de archivos de VS Code con ChatSideBar.tsx en la ventana abierta con el código pertinente para quitar la marca de comentario resaltado

  6. Vaya a react-client\src\routes\App.tsx y establezca el estado React de la showSidebar variable entrue

    Explorador de archivos de VS Code con App.tsx abierto con la línea de entrada de función useState de variable showSidebar cambiada de false a true para habilitar la visualización de la barra lateral del chat

  7. Puede seguir las instrucciones del README.md archivo en la raíz del proyecto para obtener más comandos npm. Ejecute npm run start en la raíz del proyecto para iniciar la aplicación con la funcionalidad del agente SPE habilitada.

    Nota:

    npm run start Debe realizarse en la carpeta raíz del proyecto de ejemplo. \SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction

    Terminal de VS Code en la carpeta raíz del proyecto typescript spe clonado anteriormente y el comando npm run start escrito en

  8. Inicie sesión con un usuario que tenga habilitada una licencia de Microsoft 365 Copilot.

    Aplicación SPE Typescript que se ejecuta en Edge con botones de inicio de sesión

  9. Vaya a la containers página, cree una si aún no tiene ninguna.

    Aplicación SPE Typescript que se ejecuta en edge en la subpágina /containers con modal del usuario c reatign un contenedor llamado ContosoCompanyContainer

    Una vez creado, lo verá aquí:

    Aplicación SPE Typescript que se ejecuta en el perímetro con un contenedor creado desde encima de ContosoCompanyContainer

  10. Haga clic en el contenedor y cargue los archivos. Una vez que se ha creado un contenedor y ha navegado dentro de él, la experiencia de chat del agente se habilitará.

    Aplicación SPE Typescript que se ejecuta en el perímetro dentro de una página de contenedor creada de ContosoCompanyContainer

Ejemplos

El repositorio de ejemplos incrustados de SharePoint tiene ejemplos de cómo usar SharePoint Embedded en las aplicaciones personalizadas.

  • Last updated on