клиентские библиотеки API Microsoft 365 Copilot

Клиентские библиотеки API Microsoft 365 Copilot предназначены для упрощения разработки высококачественных, эффективных и устойчивых решений ИИ, которые получают доступ к API-интерфейсам Copilot. К этим библиотекам относятся служебные и основные библиотеки.

Библиотеки служб предлагают модели и построитель запросов, которые предоставляют широкие возможности для работы с MICROSOFT 365 COPILOT API.

Основные библиотеки предлагают расширенные функции для упрощения взаимодействия с API-интерфейсами Copilot. Эти функции включают встроенную поддержку обработки повторных попыток, безопасных перенаправлений, прозрачной проверки подлинности и сжатия полезных данных. Эти возможности помогают повысить качество взаимодействия решения ИИ с API-интерфейсами Copilot без дополнительных сложностей. Кроме того, основные библиотеки упрощают рутинные задачи, такие как разбиение по страницам по коллекциям и создание пакетных запросов.

Поддерживаемые языки

Клиентские библиотеки API Copilot в настоящее время доступны для следующих языков:

• C#
• TypeScript
• Python

Клиентские библиотеки в состоянии предварительной версии

Клиентские библиотеки API Copilot могут находиться в состоянии предварительной версии при первоначальном выпуске или после значительного обновления. Избегайте использования предварительного выпуска этих библиотек в рабочих решениях независимо от того, используется ли в вашем решении версия 1.0 или бета-версия API Copilot.

Поддержка клиентских библиотек

Библиотеки API Copilot — это проекты с открытым кодом на GitHub. Если вы столкнулись с ошибкой, отправьте сообщение о проблеме с подробными сведениями на вкладке Проблемы . При необходимости участники просматривают и выпускают исправления.

Установка библиотек

Клиентские библиотеки API Copilot включены в качестве модуля в Пакет SDK агентов Microsoft 365. Эти библиотеки можно включить в проекты с помощью GitHub и популярных диспетчеров пакетов платформы.

Установка клиентских библиотек API Copilot .NET

Клиентские библиотеки API Copilot .NET доступны в следующих пакетах NuGet:

• Microsoft.Agents.M365Copilot — содержит модели и построитель запросов для доступа к конечной точке версии 1.0. Microsoft.Agents.M365Copilot зависит от Microsoft.Agents.M365Copilot.Core. Та же структура зависимостей также применяется к библиотекам TypeScript и Python.
• Microsoft.Agents.M365Copilot.Beta — содержит модели и построитель запросов для доступа к бета-точке. Microsoft.Agents.M365Copilot.Beta имеет зависимость от Microsoft.Agents.M365Copilot.Core. Та же структура зависимостей также применяется к библиотекам TypeScript и Python.
• Microsoft.Agents.M365Copilot.Core — основная библиотека для вызовов API Copilot.

Чтобы установить пакеты Microsoft.Agents.M365Copilot в проекте, используйте интерфейс командной строки dotnet, пользовательский интерфейс диспетчера пакетов в Visual Studio или консоль диспетчера пакетов в Visual Studio.

dotnet CLI

Для конечной точки версии 1.0:

dotnet add package Microsoft.Agent.M365Copilot

Для бета-версии конечной точки:

dotnet add package Microsoft.Agent.M365Copilot.Beta

Консоль диспетчера пакетов

Для конечной точки версии 1.0:

Install-Package Microsoft.Agent.M365Copilot

Для бета-версии конечной точки:

Install-Package Microsoft.Agent.M365Copilot.Beta

Установка клиентских библиотек Python api Copilot

Клиентские библиотеки Python API Copilot доступны в индексе пакета Python.

Для конечной точки версии 1.0:

pip install microsoft-agents-m365copilot

Для бета-версии конечной точки:

pip install microsoft-agents-m365copilot-beta

Установка клиентских библиотек API Copilot TypeScript

Клиентские библиотеки Api Api Copilot TypeScript доступны в npm.

Для конечной точки версии 1.0:

npm install @microsoft/agents-m365copilot –save

Для бета-версии конечной точки:

npm install @microsoft/agents-m365copilot-beta –save

Создание клиента API Copilot и вызов API

В следующем примере кода показано, как создать экземпляр клиента API Microsoft 365 Copilot с поставщиком проверки подлинности на поддерживаемых языках. Поставщик проверки подлинности обрабатывает получение маркеров доступа для приложения. Для каждого языка и платформы доступно множество различных поставщиков проверки подлинности. Разные поставщики проверки подлинности поддерживают разные клиентские сценарии. Дополнительные сведения о поставщике и параметрах, подходящих для вашего сценария, см. в разделе Выбор поставщика проверки подлинности.

В примере также показано, как выполнить вызов API извлечения. Чтобы вызвать этот API, сначала необходимо создать объект запроса, а затем запустить метод POST в запросе.

Идентификатор клиента — это идентификатор регистрации приложения, который создается при регистрации приложения в портал Azure.

C#

using Azure.Identity;
using Microsoft.Agents.M365Copilot;
using Microsoft.Agents.M365Copilot.Models;
using Microsoft.Agents.M365Copilot.Copilot.Retrieval;

var scopes = new[] {"Files.Read.All", "Sites.Read.All"};

// Multi-tenant apps can use "common",
// single-tenant apps must use the tenant ID from the Azure portal
var tenantId = "YOUR_TENANT_ID";

// Value from app registration
var clientId = "YOUR_CLIENT_ID";

// using Azure.Identity;
var deviceCodeCredentialOptions = new DeviceCodeCredentialOptions
{
   ClientId = clientId,
   TenantId = tenantId,
   // Callback function that receives the user prompt
   // Prompt contains the generated device code that user must
   // enter during the auth process in the browser
   DeviceCodeCallback = (deviceCodeInfo, cancellationToken) =>
   {
       Console.WriteLine(deviceCodeInfo.Message);
       return Task.CompletedTask;
   },
};

// https://learn.microsoft.com/dotnet/api/azure.identity.devicecodecredential
var deviceCodeCredential = new DeviceCodeCredential(deviceCodeCredentialOptions);


//Create the client
AgentsM365CopilotServiceClient client = new AgentsM365CopilotServiceClient (deviceCodeCredential, scopes, baseURL);

try
{
  var requestBody = new RetrievalPostRequestBody
  {
      DataSource = RetrievalDataSource.SharePoint,
      QueryString = "What is the latest in my organization?",
      MaximumNumberOfResults = 10
  };

  var result = await client.Copilot.Retrieval.PostAsync(requestBody);
  Console.WriteLine($"Retrieval post: {result}");

  if (result != null)
  {
    Console.WriteLine("Retrieval response received successfully");
    Console.WriteLine("\nResults:");
    Console.WriteLine(result.RetrievalHits.Count.ToString());
    if (result.RetrievalHits != null)
    {
       foreach (var hit in result.RetrievalHits)
       {
         Console.WriteLine("\n---");
         Console.WriteLine($"Web URL: {hit.WebUrl}");
         Console.WriteLine($"Resource Type: {hit.ResourceType}");
         if (hit.Extracts != null && hit.Extracts.Any())
         {
            Console.WriteLine("\nExtracts:");
            foreach (var extract in hit.Extracts)
            {
              Console.WriteLine($"  {extract.Text}");
            }
          }
          if (hit.SensitivityLabel != null)
          {
            Console.WriteLine("\nSensitivity Label:");
            Console.WriteLine($"  Display Name: {hit.SensitivityLabel.DisplayName}");
            Console.WriteLine($"  Tooltip: {hit.SensitivityLabel.Tooltip}");
            Console.WriteLine($"  Priority: {hit.SensitivityLabel.Priority}");
            Console.WriteLine($"  Color: {hit.SensitivityLabel.Color}");
            if (hit.SensitivityLabel.IsEncrypted.HasValue)
            {
              Console.WriteLine($"  Is Encrypted: {hit.SensitivityLabel.IsEncrypted.Value}");
            }
          }
        }
      }
      else
      {
        Console.WriteLine("No retrieval hits found in the response");
      }
  }
}
catch (Exception ex)
{
    Console.WriteLine($"Error making retrieval request: {ex.Message}");
    Console.Error.WriteLine(ex);
}

Python

import asyncio
import os
from datetime import datetime

from azure.identity import DeviceCodeCredential
from kiota_abstractions.api_error import APIError
from microsoft_agents_m365copilot.agents_m365_copilot_service_client import AgentsM365CopilotServiceClient
from microsoft_agents_m365copilot.generated.copilot.retrieval.retrieval_post_request_body import RetrievalPostRequestBody
from microsoft_agents_m365copilot.generated.models.retrieval_data_source import RetrievalDataSource

scopes = ['Files.Read.All', 'Sites.Read.All']

# Multi-tenant apps can use "common",
# single-tenant apps must use the tenant ID from the Azure portal
TENANT_ID = 'YOUR_TENANT_ID'

# Values from app registration
CLIENT_ID = 'YOUR_CLIENT_ID'

# Define a proper callback function that accepts all three parameters
def auth_callback(verification_uri: str, user_code: str, expires_on: datetime):
    print(f"\nTo sign in, use a web browser to open the page {verification_uri}")
    print(f"Enter the code {user_code} to authenticate.")
    print(f"The code will expire at {expires_on}")

# Create device code credential with correct callback
credentials = DeviceCodeCredential(
    client_id=CLIENT_ID,
    tenant_id=TENANT_ID,
    prompt_callback=auth_callback
)

client = AgentsM365CopilotServiceClient(credentials=credentials, scopes=scopes)

async def retrieve():
    try:
        # Print the URL being used
        print(f"Using API base URL: {client.request_adapter.base_url}\n")
        
        # Create the retrieval request body
        retrieval_body = RetrievalPostRequestBody()
        retrieval_body.data_source = RetrievalDataSource.SharePoint
        retrieval_body.query_string = "What is the latest in my organization?"
        
        # Try more parameters that might be required
        # retrieval_body.maximum_number_of_results = 10
        
        # Make the API call
        print("Making retrieval API request...")
        retrieval = await client.copilot.retrieval.post(retrieval_body)
        
        # Process the results
        if retrieval and hasattr(retrieval, "retrieval_hits"):
            print(f"Received {len(retrieval.retrieval_hits)} hits")
            for r in retrieval.retrieval_hits:
                print(f"Web URL: {r.web_url}\n")
                for extract in r.extracts:
                    print(f"Text:\n{extract.text}\n")
        else:
            print(f"Retrieval response structure: {dir(retrieval)}")
    except APIError as e:
        print(f"Error: {e.error.code}: {e.error.message}")
        if hasattr(e, 'error') and hasattr(e.error, 'inner_error'):
            print(f"Inner error details: {e.error.inner_error}")
        raise e


# Run the async function
asyncio.run(retrieve())

TypeScript

import { createBaseAgentsM365CopilotServiceClient, RetrievalDataSourceObject } from '@microsoft/agents-m365copilot';
import { DeviceCodeCredential } from '@azure/identity';
import { FetchRequestAdapter } from '@microsoft/kiota-http-fetchlibrary';
import { AzureIdentityAuthenticationProvider } from '@microsoft/kiota-authentication-azure';

async function main() {
    // Initialize authentication with Device Code flow
    const credential = new DeviceCodeCredential({
        tenantId: "YOUR_TENANT_ID",
        clientId: "YOUR_CLIENT_ID",
        userPromptCallback: (info) => {
            console.log(`\nTo sign in, use a web browser to open the page ${info.verificationUri}`);
            console.log(`Enter the code ${info.userCode} to authenticate.`);
            console.log(`The code will expire at ${info.expiresOn}`);          
        }
    });
    // Create request adapter with auth
    const authProvider = new AzureIdentityAuthenticationProvider(credential, ["Files.Read.All", "Sites.Read.All"]);
    const adapter = new FetchRequestAdapter(authProvider);

    // Create client instance
    const client = createBaseAgentsM365CopilotServiceClient(adapter);

    try {
        console.log(`Using API base URL: ${adapter.baseUrl}\n`);
        // Create the retrieval request body
        const retrievalBody = {
            dataSource: RetrievalDataSourceObject.SharePoint,
            queryString: "What is the latest in my organization?"
        };

        // Make the API call
        console.log("Making retrieval API request...");
        const retrieval = await client.copilot.retrieval.post(retrievalBody);

        // Process the results
        if (retrieval?.retrievalHits) {
            console.log(`\nReceived ${retrieval.retrievalHits.length} hits`);
            for (const hit of retrieval.retrievalHits) {
                console.log(`\nWeb URL: ${hit.webUrl}`);
                for (const extract of hit.extracts || []) {
                    console.log(`Text:\n${extract.text}\n`);
                }
            }
        }
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}  

main().catch((error) => {
    console.error('An error occurred:', error);
});

Связанные материалы

• Общие сведения об API получения Microsoft 365 Copilot
• Использование API извлечения