使用智能 Microsoft 365 Copilot 副驾驶®检索 API 检索地面数据

重要

版本下的 /beta API 可能会更改。 不支持在生产应用程序中使用这些 API。

使用 Microsoft 365 数据优化生成 AI 解决方案，同时针对上下文召回进行优化。 允许从调用用户有权访问的 SharePoint 和 Copilot 连接器内容检索相关文本提取，同时遵守租户中定义的访问控制。 尝试向智能 Microsoft 365 Copilot 副驾驶®检索 API 发出第一个查询。 了解如何 对检索 API 最多 20 个请求进行批处理。

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Files.Read.All	Sites.Read.All、ExternalItem.Read.All
委派（个人 Microsoft 帐户）	不支持。	不支持。
应用程序	不支持。	不支持。

HTTP 请求

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

请求标头

名称	说明
Authorization	持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type	application/json. 必需。

请求正文

在请求正文中，提供参数的 JSON 表示形式。

下表列出了调用此作时所需的参数。

参数	类型	说明
queryString	String	用于检索相关文本提取的自然语言查询字符串。 此参数的限制为 1,500 个字符。 应 queryString 是单个句子，应避免在上下文丰富的关键字中出现拼写错误。 必填。
dataSource	String	指示是否应从 SharePoint 或 Copilot 连接器检索提取的字符串。 可接受的值为“sharePoint”和“externalItem”。 必填。
filterExpression	String	关键字查询语言 (KQL) 表达式，其中包含可查询 SharePoint 和 Copilot 连接器属性和属性，以在查询运行之前限定检索范围。 在构造 filterExpression时，可以使用 AND、OR、 NOT和 不等运算符（如果适用）。 支持的用于筛选的 SharePoint 属性包括：Author、、FilenameLastModifiedTimeFileTypeModifiedByFileExtensionInformationProtectionLabelId、Path、、 SiteID和 。Title 筛选 Copilot 连接器内容时，可以使用 Copilot 连接器架构中标记为可查询的任何属性。 如果不熟悉所需 Copilot 连接器的架构，或者不知道哪些属性标记为可查询，请联系配置所需 Copilot 连接器的管理员或开发人员。 Microsoft不会解决此处未提及的 SharePoint 和 Copilot 连接器属性上筛选的任何问题。 构造 filterExpression时，可以使用多个属性和运算符。 默认情况下，不应用任何范围。 在调用 API 之前，请确保此参数具有正确的 KQL 语法。 否则，查询的执行方式就好像没有 filterExpression。 请针对筛选的查询遵循这些 最佳做法 。 可选。
resourceMetadata	字符串集合	要为响应中的每个项返回的元数据字段列表。 此列表中只能包含可检索的元数据属性。 默认情况下，不返回元数据。 可选。
maximumNumberOfResults	Int32	响应中返回的最大文档数。 默认情况下，最多返回 25 个结果。 可选。

响应

如果成功，此作将在 200 OK 响应正文中返回响应代码和 retrievalResponse 。

示例

示例 1：从 SharePoint 检索数据

以下示例显示了从 SharePoint 检索数据的请求。 请求要求 title 为从中检索文本提取的每个项返回 和 author 元数据。 响应最多包含 10 个文档。

请求

下面为请求示例。

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": "10"
}

响应

以下示例显示了相应的响应。

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials."
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "Corporate VPN",
        "author": "Jane Doe"
      },
        "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    }
  ]
}

示例 2：从 Copilot 连接器检索数据

以下示例显示了从 Copilot 连接器检索数据的请求。 请求要求 title 为从中检索文本提取的每个项返回 和 author 元数据。 响应最多包含 10 个文档。

请求

下面为请求示例。

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": "10"
}

响应

以下示例显示了相应的响应。

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN."
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials."
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with acessing the VPN."
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

示例 3：对检索 API 的批处理请求

以下示例演示如何 对检索 API 发出批处理请求。 检索 API 每批最多支持 20 个请求。 id 请求有效负载必须是唯一标识批处理中的每个请求的字符串。

请求

下面为请求示例。

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

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "sharePoint"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "externalItem"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

响应

以下示例显示了相应的响应。

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

{
  "responses": [
    {
      "id": "1",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN."
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00",
              "isEncrypted": false
            }
          },
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials."
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN."
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00",
              "isEncrypted": false
            }
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN."
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          },
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials."
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with acessing the VPN."
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          }
        ]
      }
    }
  ]
}

示例 4：从特定 SharePoint 网站检索数据

以下示例显示了从特定 Sharepoint 网站检索数据的请求。 参数 filterExpression 指定站点的路径。 请求要求 title 为从中检索文本提取的每个项返回 和 author 元数据。 响应最多应包含四个文档。

请求

下面为请求示例。

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": "4"
}

响应

以下示例显示了相应的响应。

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration."
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    }
  ]
}

示例 5：从多个 SharePoint 网站检索数据

以下示例显示了从多个 Sharepoint 网站检索数据的请求。 参数 filterExpression 指定站点的路径。 请求要求 title 为从中检索文本提取的每个项返回 和 author 元数据。 响应最多应包含四个文档。

请求

下面为请求示例。

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": "4"
}

响应

以下示例显示了相应的响应。

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option."
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Config",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration."
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources."
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00",
        "isEncrypted": false
      }
    }
  ]
}

示例 6：使用筛选器表达式

下面是可用于特定方案的 属性中的 filterExpression KQL 表达式示例。

对 Copilot 连接器属性进行筛选

在此示例中， Label_Title 是 ServiceNow Copilot 连接器架构中的可查询属性。 查询根据 属性中包含的Corporate VPNLabel_Title项进行筛选。

"filterExpression": "Label_Title:\"Corporate VPN\""

筛选属性上的 Author SharePoint 结果

在此示例中，查询将针对以 Megan Bowen 为作者的项进行筛选。

"filterExpression": "Author:\"Megan Bowen\""

使用 LastModifiedTime 属性筛选特定日期范围的 SharePoint 结果

在此示例中，查询筛选在 2024 年 7 月 22 日至 2025 年 1 月 8 日之间修改的项目。

"filterExpression": "LastModifiedTime >= 2024-07-22 AND LastModifiedTime <= 2025-01-08"

使用 FileExtension 属性筛选 SharePoint 结果

在此示例中，查询按文件扩展名为 .docx、.pdf 或 .pptx 的文件进行筛选。

"filterExpression": "FileExtension:\"docx\" OR FileExtension:\"pdf\" OR FileExtension:\"pptx\""

使用 Filename 属性筛选 SharePoint 结果

在此示例中，查询根据名为 Contoso Mission Statement.docx的文件进行筛选。

"filterExpression": "Filename:\"Contoso Mission Statement.docx\""

使用 FileType 属性筛选 SharePoint 结果

在此示例中，查询按 PDF 文件、PowerPoint 演示文稿和Word文档进行筛选。

"filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\""

通过使用 InformationProtectionLabelId 属性进行筛选来确定 SharePoint 结果的敏感度

在此示例中，查询按具有特定信息保护标签的项进行筛选。

"filterExpression": "InformationProtectionLabelId:\"f0ddcc93-d3c0-4993-b5cc-76b0a283e252\""

使用 ModifiedBy 属性筛选 SharePoint 结果

在此示例中，查询根据 Adele Vance 修改的项进行筛选。

"filterExpression": "ModifiedBy:\"Adele Vance\""

使用 SiteID 属性筛选 SharePoint 结果

在此示例中，查询按特定 SharePoint 网站中的项目进行筛选。

"filterExpression": "SiteID:\"e2cf7e40-d689-41de-99ee-a423811a253c\""

使用 Title 属性筛选 SharePoint 结果

在此示例中，查询按标题中的项 Windows 10 Device 进行筛选。

"filterExpression": "Title:\"Windows 10 Device\""

相关内容

• 智能 Microsoft 365 Copilot 副驾驶®检索 API 概述
• 使用 Graph 资源管理器试用