Microsoft 365 Copilot Search API を使用して検索を実行する

重要

/beta バージョンの API は変更される可能性があります。実稼働アプリケーションでこれらの API を使用することは、サポートされていません。

コンテキストを理解した自然言語クエリを使用して、OneDrive 全体で職場または学校のコンテンツに対してハイブリッド (セマンティックおよび字句) 検索を実行します。 organization内の定義済みのアクセス制御を尊重しながら、アクセス権を持つ関連するドキュメントとファイルを検出します。 Microsoft 365 Copilot Search API に対して最初のクエリを発行してみてください。 Search API に対して最大 20 件の要求をバッチ処理する方法について説明します。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	❌	❌	❌

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。職場または学校のデータソースの OneDrive からデータにアクセスするには、Files.Read.All または Files.ReadWrite.All アクセス許可が必要です。また、Sites.Read.All または Sites.ReadWrite.All のアクセス許可も必要です。

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	Files.Read.All、Sites.Read.All	Files.ReadWrite.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
アプリケーション	サポートされていません。	サポートされていません。

HTTP 要求

POST https://graph.microsoft.com/beta/copilot/search

要求ヘッダー

名前	説明
`Authorization`	`Bearer {token}`. 必須です。認証と認可についての詳細をご覧ください。
`Content-Type`	`application/json`. 必須です。

要求本文

要求本文で、パラメーターの JSON 表現を指定します。

次の表に、このアクションを呼び出すときに必要なパラメーターを示します。

パラメーター	型	説明
`query`	文字列	関連するファイルを検索する自然言語クエリ。最大 1,500 文字。必須です。
`pageSize`	Int32	1 ページあたりに返す結果の数 (1 から 100)。既定値: 25。省略可能。
`dataSources`	copilotSearchDataSourcesConfiguration	検索に含めるデータソースの構成。省略可能。

応答

成功した場合、このアクションは応答本文に 200 OK 応答コードと copilotSearchResponse を返します。

例

例 1: 基本検索要求

次の例は、職場または学校のコンテンツに対して OneDrive 全体でハイブリッド検索 (セマンティックと字句) を実行するために必要な最小パラメーターを示しています。

要求

次の例は要求を示しています。 Graph エクスプローラーでこの例をお試しください。

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "How to setup corporate VPN?"
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "totalCount": 2,
  "searchHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/VPNAccess.docx",
      "preview": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option...",
      "resourceType": "driveItem"
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/Corporate_VPN.docx",
      "preview": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials...",
      "resourceType": "driveItem"
    }
  ]
}

例 2: フィルター処理とメタデータを使用した検索

次の例は、特定の OneDrive パスフィルター処理とメタデータコレクションを含む要求を示しています。要求は、検索結果ごとに title と author メタデータを返すように求めます。

要求

次の例は要求を示しています。 Graph エクスプローラーでこの例をお試しください。

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "quarterly budget analysis",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/\" OR path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.nextLink": "https://graph.microsoft.com/beta/copilot/searchNextPage?$skipToken=eyJDb250aW51YXRpb25Ub2tlbiI6...",
  "totalCount": 24,
  "searchHits": [
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/Q1_Budget_Analysis.xlsx",
      "preview": "This quarterly budget analysis shows significant improvements in operational efficiency and cost reduction across all departments...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Q1 Budget Analysis 2025",
        "author": "Megan Bowen"
      }
    },
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget/Annual_Financial_Review.docx",
      "preview": "The annual financial review demonstrates strong performance indicators and provides recommendations for the upcoming quarter...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Annual Financial Review",
        "author": "Alex Wilber"
      }
    }
  ]
}

例 3: パスベースのフィルター処理を使用して検索する

次の例では、キーワード照会言語 (KQL) パス式を使用して特定の OneDrive パス内を検索する方法を示します。

要求

次の例は要求を示しています。 Graph エクスプローラーでこの例をお試しください。

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "project timeline milestones",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "totalCount": 12,
  "searchHits": [
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/Project_Timeline_2026.docx",
      "preview": "The project timeline outlines key milestones for Q1 and Q2, including deliverable dates and resource requirements...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Project Timeline 2026",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/Milestone_Review.pptx",
      "preview": "Milestone review presentation covering completed deliverables, upcoming deadlines, and project status updates...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Milestone Review Presentation",
        "author": "Sarah Connor"
      }
    }
  ]
}

例 4: Search API へのバッチ要求

次の例は、 Search API への要求をバッチ処理する方法を示しています。 Search API では、バッチあたり最大 20 個の要求がサポートされます。要求ペイロード内の id は、バッチ内の各要求を一意に識別する文字列である必要があります。

要求

次の例は要求を示しています。 Graph エクスプローラーでこの例をお試しください。

POST https://graph.microsoft.com/beta/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "quarterly budget reports"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "project planning documents"
      }
    }
  ]
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "totalCount": 15,
        "searchHits": [
          {
            "webUrl": "https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/Finance/Q1_Budget.xlsx",
            "preview": "Q1 budget analysis showing revenue growth and expense optimization across departments...",
            "resourceType": "driveItem"
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "totalCount": 8,
        "searchHits": [
          {
            "webUrl": "https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/Projects/Planning_Guide.docx",
            "preview": "Comprehensive project planning guide with templates and best practices for successful delivery...",
            "resourceType": "driveItem"
          }
        ]
      }
    }
  ]
}

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-21

次の方法で共有

Microsoft 365 Copilot Search API を使用して検索を実行する

アクセス許可

HTTP 要求

要求ヘッダー

要求本文

応答

例

例 1: 基本検索要求

要求

応答

例 2: フィルター処理とメタデータを使用した検索

要求

応答

例 3: パスベースのフィルター処理を使用して検索する

要求

応答

例 4: Search API へのバッチ要求

要求

応答

関連コンテンツ

フィードバック

その他のリソース