グラウンディング データの取得

重要

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

Microsoft 365 Copilot Retrieval API は、SharePoint、OneDrive、Copilot コネクタのコンテンツから関連するテキスト抽出を取得します。 API セキュリティは、呼び出し元ユーザーのコンテンツをトリミングし、テナント内で定義されたアクセス制御を尊重します。 Retrieval API を使用して、コンテキストの再現を最適化しながら、Microsoft 365 データを使用して生成 AI ソリューションを基盤とします。

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

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

アクセス許可

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

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

* SharePoint と OneDrive のコンテンツを取得するには、両方の Files が必要です。Read.All および Sites.Read.All のアクセス許可が必要です。

HTTP 要求

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

POST https://graph.microsoft.com/v1.0/copilot/retrieval

要求ヘッダー

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

要求本文

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

次の表に、このアクションを呼び出すときに使用できるオプションのパラメーターと必須のパラメーターを示します。

パラメーター 型 説明
queryString 文字列 関連するテキスト抽出を取得するために使用される自然言語のクエリ文字列。 このパラメーターの文字数制限は 1,500 文字です。 queryStringは 1 つの文にする必要があり、コンテキストが豊富なキーワードでのスペル ミスを避ける必要があります。 必須です。
dataSource 文字列 抽出を SharePoint、OneDrive、または Copilot コネクタから取得する必要があるかどうかを示します。 指定できる値は、 sharePoint、 oneDriveBusiness、 externalItem です。 必須です。
dataSourceConfiguration dataSourceConfiguration 適用可能なデータ ソースの追加構成情報が含まれています。 dataSourceConfiguration externalItem というオブジェクトが含まれており、Copilot コネクタの取得を構成できます。 省略可能。
filterExpression 文字列 クエリ実行前に取得の範囲を指定するための、クエリ可能な SharePoint、OneDrive、または Copilot コネクタのプロパティと属性を持つキーワード照会言語 (KQL) 式。 filterExpressionを作成するときは、該当する場合は、AND、OR、NOT、不等式演算子を使用できます。 フィルター処理でサポートされている SharePoint および OneDrive のプロパティは、 Author、 FileExtension、 Filename、 FileType、 InformationProtectionLabelId、 LastModifiedTime、 ModifiedBy、 Path、 SiteID、 Title です。 Copilot コネクタのコンテンツでフィルター処理するときは、 Copilot コネクタ スキーマでクエリ可能としてマークされた任意のプロパティを使用できます。 クエリ可能とマークされたプロパティの一覧について、目的の Copilot コネクタを構成した管理者または開発者に連絡してください。 Microsoft は、ここに記載されていない SharePoint および Copilot コネクタ プロパティのフィルター処理に関する問題を解決しません。 filterExpressionを作成するときに、複数のプロパティと演算子を使用できます。 既定では、範囲設定は適用されません。 API を呼び出す前に、このパラメーターの KQL 構文が正しいことを確認してください。 それ以外の場合、クエリは filterExpressionがないかのように実行されます。 省略可能。 フィルター処理されたクエリのベスト プラクティスについては、「 ベスト プラクティス」を参照してください。
resourceMetadata String collection 応答内の各項目に対して返されるメタデータ フィールドのリスト。 この一覧に含めることができるのは、取得可能なメタデータ プロパティのみです。 既定では、メタデータは返されません。 省略可能。
maximumNumberOfResults Int32 応答で返される結果の数。 1 から 25 の間である必要があります。 既定では、最大 25 件の結果を返します。 省略可能。
パラメーター 型 説明
queryString 文字列 関連するテキスト抽出を取得するために使用される自然言語のクエリ文字列。 このパラメーターの文字数制限は 1,500 文字です。 queryStringは 1 つの文にする必要があり、コンテキストが豊富なキーワードでのスペル ミスを避ける必要があります。 必須です。
dataSource 文字列 抽出を SharePoint、OneDrive、または Copilot コネクタから取得する必要があるかどうかを示します。 指定できる値は、 sharePoint、 oneDriveBusiness、 externalItem です。 必須です。
dataSourceConfiguration dataSourceConfiguration 適用可能なデータ ソースの追加構成情報が含まれています。 dataSourceConfiguration externalItem というオブジェクトが含まれており、Copilot コネクタの取得を構成できます。 省略可能。
filterExpression 文字列 クエリ実行前に取得の範囲を指定するための、クエリ可能な SharePoint、OneDrive、または Copilot コネクタのプロパティと属性を持つキーワード照会言語 (KQL) 式。 filterExpressionを作成するときは、該当する場合は、AND、OR、NOT、不等式演算子を使用できます。 フィルター処理でサポートされている SharePoint および OneDrive のプロパティは、 Author、 FileExtension、 Filename、 FileType、 InformationProtectionLabelId、 LastModifiedTime、 ModifiedBy、 Path、 SiteID、 Title です。 Copilot コネクタのコンテンツでフィルター処理するときは、 Copilot コネクタ スキーマでクエリ可能としてマークされた任意のプロパティを使用できます。 クエリ可能とマークされたプロパティの一覧について、目的の Copilot コネクタを構成した管理者または開発者に連絡してください。 Microsoft は、ここに記載されていない SharePoint および Copilot コネクタ プロパティのフィルター処理に関する問題を解決しません。 filterExpressionを作成するときに、複数のプロパティと演算子を使用できます。 既定では、範囲設定は適用されません。 API を呼び出す前に、このパラメーターの KQL 構文が正しいことを確認してください。 それ以外の場合、クエリは filterExpressionがないかのように実行されます。 省略可能。 フィルター処理されたクエリのベスト プラクティスについては、「 ベスト プラクティス」を参照してください。
resourceMetadata String collection 応答内の各項目に対して返されるメタデータ フィールドのリスト。 この一覧に含めることができるのは、取得可能なメタデータ プロパティのみです。 既定では、メタデータは返されません。 省略可能。
maximumNumberOfResults Int32 応答で返される結果の数。 1 から 25 の間である必要があります。 既定では、最大 25 件の結果を返します。 省略可能。
includeThumbnails ブール型 ページ番号とサムネイルを含めるかどうかを指定します (使用可能な場合)。 複数の抽出が同じページを参照している場合、取得ヒットで関連付けられているサムネイルの 1 つのコピーのみが返されます。 省略可能。

応答

成功した場合、このアクションは 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
}

POST https://graph.microsoft.com/v1.0/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.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "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"
      }
    },
    {
      "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.",
          "relevanceScore": 0.7588038775683956
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.6696818957446697
        }
      ],
      "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"
      }
    }
  ]
}

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

POST https://graph.microsoft.com/v1.0/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.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "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 accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

例 3: 取得 API へのバッチ要求

次の例は、 取得 API への要求をバッチ処理する方法を示しています。 Retrieval 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"
      }
    }
  ]
}

POST https://graph.microsoft.com/v1.0/$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.",
                "relevanceScore": 0.8374363553387588
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.7465472642498679
              }
            ],
            "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"
            }
          },
          {
            "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.",
                "relevanceScore": 0.7588038775683956
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.6696818957446697
              }
            ],
            "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"
            }
          }
        ]
      }
    },
    {
      "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.",
                "relevanceScore": 0.874
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.801
              }
            ],
            "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.",
                "relevanceScore": 0.772
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.655
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          }
        ]
      }
    }
  ]
}

例 4:特定の SharePoint サイトからデータを取得する

次の例は、特定の SharePoint サイトからデータを取得する要求を示しています。 filterExpression パラメーターは、サイトへのパスを指定します。 この要求では、テキストの抽出を取得する項目ごとに返される title と author のメタデータが要求されます。 応答には、最大 4 つのドキュメントが含まれます。

要求

次の例は要求を示しています。

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
}

POST https://graph.microsoft.com/v1.0/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.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "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"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "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"
      }
    }
  ]
}

例 5:複数の SharePoint サイトからデータを取得する

次の例は、複数の SharePoint サイトからデータを取得する要求を示しています。 filterExpression パラメーターは、サイトへのパスを指定します。 この要求では、テキストの抽出を取得する項目ごとに返される title と author のメタデータが要求されます。 応答には、最大 4 つのドキュメントを含める必要があります。

要求

次の例は要求を示しています。

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
}

POST https://graph.microsoft.com/v1.0/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.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "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"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        }
      ],
      "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"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "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"
      }
    }
  ]
}

例 6: 特定の接続 ID を使用して Copilot コネクタからデータを取得する

次の例は、Copilot コネクタの取得を特定の接続 ID に制限する要求を示しています。 この要求では、テキストの抽出を取得する項目ごとに返される title と author のメタデータが要求されます。 応答には、最大 10 個のドキュメントが含まれます。

要求

次の例は要求を示しています。

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

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

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "dataSourceConfiguration": {
    "externalItem": {
      "connections": [
        {
          "connectionId": "ContosoITServiceNowKB"
        },
        {
          "connectionId": "ContosoHRServiceNowKB"
        }
      ]
    }
  },
  "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.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "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.",
          "relevanceScore": 0.772
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

例 7: フィルター式を使用する

次の例は、特定のシナリオの filterExpression プロパティで使用できる KQL 式を示しています。

Copilot コネクタのプロパティでフィルター処理する

この例では、Label_Title は ServiceNow Copilot コネクタ スキーマ内のクエリ可能なプロパティです。 クエリは、Label_Title プロパティに Corporate VPN を含むアイテムをフィルター処理します。

"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\""

例 8: 抜粋のサムネイルを含める

次の例は、 includeThumbnails プロパティを追加する要求と、サムネイルと関連するページ番号を含む関連する応答を示しています。

要求

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 2,
  "includeThumbnails": true
}

応答

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

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.",
          "relevanceScore": 0.8374363553387588,
          "pageNumbers": [
            1
          ]
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679,
          "pageNumbers": [
            2
          ]
        }
      ],
      "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"
      },
      "thumbnails": [
        {
          "pageNumber": 1,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
        {
          "pageNumber": 2,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
      ]
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679,
          "pageNumbers": [
            1,2
          ]
        }
      ],
      "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"
      }
    }
  ]
}

関連コンテンツ

  • Last updated on