Microsoft 365 Copilot API クライアント ライブラリ

Microsoft 365 Copilot API クライアント ライブラリは、Copilot API にアクセスする高品質で効率的で回復力のある AI ソリューションの開発を容易にするように設計されています。 これらのライブラリには、サービス ライブラリとコア ライブラリが含まれます。

サービス ライブラリは、Microsoft 365 Copilot API を操作するための豊富な型指定されたエクスペリエンスを提供するモデルと要求ビルダーを提供します。

コア ライブラリには、Copilot API との対話を容易にする高度な機能が用意されています。 これらの機能には、再試行処理、セキュリティで保護されたリダイレクト、透過的な認証、ペイロード圧縮の埋め込みサポートが含まれます。 これらの機能は、複雑さを追加することなく、Copilot API との AI ソリューションの通信の品質を高めるのに役立ちます。 さらに、コア ライブラリは、コレクションを介したページングやバッチ要求の作成などの日常的なタスクを簡略化します。

サポートされている言語

Copilot API クライアント ライブラリは現在、次の言語で使用できます。

• C#
• TypeScript
• Python

プレビュー状態のクライアント ライブラリ

Copilot API クライアント ライブラリは、最初にリリースされたとき、または大幅な更新後にプレビュー状態になる可能性があります。 ソリューションでバージョン 1.0 と Copilot API のベータ 版のどちらを使用しているかに関係なく、運用環境のソリューションでこれらのライブラリのプレビュー リリースを使用しないでください。

クライアント ライブラリのサポート

Copilot API ライブラリは、GitHub 上のオープンソース プロジェクトです。 バグが発生した場合は、[ 問題] タブ の詳細に問題を報告します。共同作成者は、必要に応じて修正プログラムを確認してリリースします。

ライブラリをインストールする

Copilot API クライアント ライブラリは、Microsoft 365 エージェント SDKのモジュールとして含まれています。 これらのライブラリは、GitHub と一般的なプラットフォーム パッケージ マネージャーを使用してプロジェクトに含めることができます。

Copilot API .NET クライアント ライブラリをインストールする

Copilot API .NET クライアント ライブラリは、次の NuGet パッケージで使用できます。

• Microsoft.Agents.M365Copilot - v1.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 - Copilot API を呼び出すコア ライブラリ。

Microsoft.Agents.M365Copilot パッケージをプロジェクトにインストールするには、 dotnet CLI、 Visual Studio のパッケージ マネージャー UI、または Visual Studio のパッケージ マネージャー コンソールを使用します。

dotnet CLI

v1.0 エンドポイントの場合:

dotnet add package Microsoft.Agent.M365Copilot

ベータ エンドポイントの場合:

dotnet add package Microsoft.Agent.M365Copilot.Beta

パッケージ マネージャー コンソール

v1.0 エンドポイントの場合:

Install-Package Microsoft.Agent.M365Copilot

ベータ エンドポイントの場合:

Install-Package Microsoft.Agent.M365Copilot.Beta

Copilot API Python クライアント ライブラリをインストールする

Copilot API Python クライアント ライブラリは、Python パッケージ インデックスで使用できます。

v1.0 エンドポイントの場合:

pip install microsoft-agents-m365copilot

ベータ エンドポイントの場合:

pip install microsoft-agents-m365copilot-beta

Copilot API TypeScript クライアント ライブラリをインストールする

Copilot API TypeScript クライアント ライブラリは npm で使用できます。

v1.0 エンドポイントの場合:

npm install @microsoft/agents-m365copilot –save

ベータ エンドポイントの場合:

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

Copilot API クライアントを作成し、API 呼び出しを行う

次のコード例は、サポートされている言語で認証プロバイダーを使用して、Microsoft 365 Copilot API クライアントのインスタンスを作成する方法を示しています。 認証プロバイダーは、アプリケーションのアクセス トークンの取得を処理します。 言語とプラットフォームごとに、さまざまな認証プロバイダーを利用できます。 さまざまな認証プロバイダーは、さまざまなクライアント シナリオをサポートします。 シナリオに適したプロバイダーとオプションの詳細については、「認証プロバイダーの選択」を参照してください。

この例では、取得 API を呼び出す方法も示しています。 この API を呼び出すには、最初に要求オブジェクトを作成してから、要求に対して POST メソッドを実行する必要があります。

クライアント ID は、Azure portalでアプリを登録するときに生成されるアプリ登録 ID です。

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

関連コンテンツ

• Microsoft 365 Copilot取得 API の概要
• 取得 API を使用する