Abrufen von Erdungsdaten

Wichtig

APIs unter der /beta Version können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.

Die Microsoft 365 Copilot Retrieval-API ruft relevante Textauszüge aus SharePoint-, OneDrive- und Copilot-Connectorsinhalten ab. Die API-Sicherheit schneidet Inhalte für den aufrufenden Benutzer zu und respektiert die definierten Zugriffskontrollen innerhalb des Mandanten. Verwenden Sie die Retrieval-API, um Ihre generativen KI-Lösungen mit Microsoft 365-Daten zu verankern und gleichzeitig für den Kontextabruf zu optimieren.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service	US Government L4	US Government L5 (DOD)	China, betrieben von 21Vianet
✅	❌	❌	❌

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp	Berechtigungen mit den geringsten Berechtigungen	Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto)	Files. Read.All, Sites.Read.All*	ExternalItem.Read.All
Delegiert (persönliches Microsoft-Konto)	Nicht unterstützt	Nicht unterstützt
Application	Nicht unterstützt	Nicht unterstützt

* Zum Abrufen von SharePoint- und OneDrive-Inhalten benötigen Sie beide Files. Read.All und Sites.Read.All.

HTTP-Anforderung

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

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

Anforderungsheader

Name	Beschreibung
`Authorization`	`Bearer {token}`. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
`Content-Type`	`application/json.` Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung der Parameter an.

In der folgenden Tabelle sind die optionalen und erforderlichen Parameter aufgeführt, die Sie beim Aufrufen dieser Aktion verwenden können.

Parameter	Typ	Beschreibung
`queryString`	Zeichenfolge	Abfragezeichenfolge in natürlicher Sprache, die zum Abrufen relevanter Textauszüge verwendet wird. Dieser Parameter darf maximal 1.500 Zeichen lang sein. Ihr Text `queryString` sollte aus einem einzigen Satz bestehen, und Sie sollten Rechtschreibfehler in kontextreichen Schlüsselwörtern vermeiden. Erforderlich.
`dataSource`	Zeichenfolge	Gibt an, ob Extrakte aus SharePoint-, OneDrive- oder Copilot-Connectors abgerufen werden sollen. Zulässige Werte sind `sharePoint`, `oneDriveBusiness`, und `externalItem`. Erforderlich.
`dataSourceConfiguration`	dataSourceConfiguration	Enthält zusätzliche Konfigurationsinformationen für anwendbare Datenquellen. `dataSourceConfiguration` enthält ein Objekt mit dem Namen `externalItem`, in dem Sie das Abrufen von Copilot-Connectors konfigurieren können. Optional.
`filterExpression`	Zeichenfolge	Keyword Query Language (KQL)-Ausdruck mit abfragbaren SharePoint-, OneDrive- oder Copilot-Connectoreigenschaften und -attributen, um den Abruf vor der Ausführung der Abfrage zu begrenzen. Sie können beim Erstellen des Felds ggf`filterExpression`. . , und Ungleichheitsoperatoren verwenden. `NOTANDOR` Unterstützte SharePoint- und OneDrive-Eigenschaften für die Filterung sind: `Author`, `FileExtension`, `Filename`, `ModifiedByLastModifiedTimeInformationProtectionLabelIdPathFileTypeSiteID`und .`Title` Beim Filtern nach Copilot-Connectorinhalten können Sie jede Eigenschaft verwenden, die im Copilot-Connectorschema als abfragbar markiert ist. Wenden Sie sich an den Administrator oder Entwickler, der den gewünschten Copilot-Connector konfiguriert hat, um eine Liste der als abfragbar markierten Eigenschaften zu erhalten. Microsoft löst keine Probleme mit der Filterung von SharePoint- und Copilot-Connectors-Eigenschaften, die hier nicht erwähnt werden. Sie können beim Erstellen Ihrer .`filterExpression` Standardmäßig wird keine Bereichsdefinition angewendet. Stellen Sie sicher, dass dieser Parameter über die richtige KQL-Syntax verfügt, bevor Sie die API aufrufen. Andernfalls wird die Abfrage so ausgeführt, als gäbe es keine `filterExpression`. Optional. Bewährte Methoden für gefilterte Abfragen finden Sie unter Bewährte Methoden.
`resourceMetadata`	String collection	Eine Liste der Metadatenfelder, die für jedes Element in der Antwort zurückgegeben werden sollen. In dieser Liste können nur abrufbare Metadateneigenschaften enthalten sein. Standardmäßig werden keine Metadaten zurückgegeben. Optional.
`maximumNumberOfResults`	Int32	Die Anzahl der Ergebnisse, die in der Antwort zurückgegeben werden. Muss zwischen 1 und 25 liegen. Gibt standardmäßig bis zu 25 Ergebnisse zurück. Optional.

Parameter	Typ	Beschreibung
`queryString`	Zeichenfolge	Abfragezeichenfolge in natürlicher Sprache, die zum Abrufen relevanter Textauszüge verwendet wird. Dieser Parameter darf maximal 1.500 Zeichen lang sein. Ihr Text `queryString` sollte aus einem einzigen Satz bestehen, und Sie sollten Rechtschreibfehler in kontextreichen Schlüsselwörtern vermeiden. Erforderlich.
`dataSource`	Zeichenfolge	Gibt an, ob Extrakte aus SharePoint-, OneDrive- oder Copilot-Connectors abgerufen werden sollen. Zulässige Werte sind `sharePoint`, `oneDriveBusiness`, und `externalItem`. Erforderlich.
`dataSourceConfiguration`	dataSourceConfiguration	Enthält zusätzliche Konfigurationsinformationen für anwendbare Datenquellen. `dataSourceConfiguration` enthält ein Objekt mit dem Namen `externalItem`, in dem Sie das Abrufen von Copilot-Connectors konfigurieren können. Optional.
`filterExpression`	Zeichenfolge	Keyword Query Language (KQL)-Ausdruck mit abfragbaren SharePoint-, OneDrive- oder Copilot-Connectoreigenschaften und -attributen, um den Abruf vor der Ausführung der Abfrage zu begrenzen. Sie können beim Erstellen des Felds ggf`filterExpression`. . , und Ungleichheitsoperatoren verwenden. `NOTANDOR` Unterstützte SharePoint- und OneDrive-Eigenschaften für die Filterung sind: `Author`, `FileExtension`, `Filename`, `ModifiedByLastModifiedTimeInformationProtectionLabelIdPathFileTypeSiteID`und .`Title` Beim Filtern nach Copilot-Connectorinhalten können Sie jede Eigenschaft verwenden, die im Copilot-Connectorschema als abfragbar markiert ist. Wenden Sie sich an den Administrator oder Entwickler, der den gewünschten Copilot-Connector konfiguriert hat, um eine Liste der als abfragbar markierten Eigenschaften zu erhalten. Microsoft löst keine Probleme mit der Filterung von SharePoint- und Copilot-Connectors-Eigenschaften, die hier nicht erwähnt werden. Sie können beim Erstellen Ihrer .`filterExpression` Standardmäßig wird keine Bereichsdefinition angewendet. Stellen Sie sicher, dass dieser Parameter über die richtige KQL-Syntax verfügt, bevor Sie die API aufrufen. Andernfalls wird die Abfrage so ausgeführt, als gäbe es keine `filterExpression`. Optional. Bewährte Methoden für gefilterte Abfragen finden Sie unter Bewährte Methoden.
`resourceMetadata`	String collection	Eine Liste der Metadatenfelder, die für jedes Element in der Antwort zurückgegeben werden sollen. In dieser Liste können nur abrufbare Metadateneigenschaften enthalten sein. Standardmäßig werden keine Metadaten zurückgegeben. Optional.
`maximumNumberOfResults`	Int32	Die Anzahl der Ergebnisse, die in der Antwort zurückgegeben werden. Muss zwischen 1 und 25 liegen. Gibt standardmäßig bis zu 25 Ergebnisse zurück. Optional.
`includeThumbnails`	Boolean	Gibt an, ob Seitenzahlen und Miniaturansichten in die Abrufantwort eingeschlossen werden sollen, falls verfügbar. Wenn mehrere Extrakte auf dieselbe Seite verweisen, wird nur eine einzige Kopie der zugehörigen Miniaturansicht mit dem Abruftreffer zurückgegeben. Optional.

Antwort

Bei erfolgreicher Ausführung gibt diese Aktion einen 200 OK Antwortcode und eine retrievalResponse im Antworttext zurück.

Beispiele

Beispiel 1: Abrufen von Daten aus SharePoint

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten aus SharePoint. Die Anforderung verlangt, dass die titleauthor und-Metadaten für jedes Element zurückgegeben werden, aus dem ein Textauszug abgerufen wird. Die Antwort umfasst maximal 10 Dokumente.

Anforderung

Das folgende Beispiel zeigt die Antwort.

▶ Probieren Sie es in der interaktiven Demo aus

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Beispiel 2: Abrufen von Daten von Copilot-Connectors

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten von Copilot-Connectors. Die Anforderung verlangt, dass die titleauthor und-Metadaten für jedes Element zurückgegeben werden, aus dem ein Textauszug abgerufen wird. Die Antwort umfasst maximal 10 Dokumente.

Anforderung

Das folgende Beispiel zeigt die Antwort.

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Beispiel 3: Batchanforderungen an die Retrieval-API

Im folgenden Beispiel werden Batchanforderungen an die Retrieval-API gezeigt. Die Retrieval-API unterstützt bis zu 20 Anforderungen pro Batch. Die id in der Anforderungsnutzlast muss eine Zeichenfolge sein, die jede Anforderung im Batch eindeutig identifiziert.

Anforderung

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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": {}
          }
        ]
      }
    }
  ]
}

Beispiel 4: Abrufen von Daten von einer bestimmten SharePoint-Website

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten von einer bestimmten SharePoint-Website. Der filterExpression Parameter gibt den Pfad zur Website an. Die Anforderung verlangt, dass die titleauthor und-Metadaten für jedes Element zurückgegeben werden, aus dem ein Textauszug abgerufen wird. Die Antwort umfasst bis zu vier Dokumente.

Anforderung

Das folgende Beispiel zeigt die Antwort.

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Beispiel 5: Abrufen von Daten von mehreren SharePoint-Websites

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten von mehreren SharePoint-Websites. Der filterExpression Parameter gibt die Pfade zu den Websites an. Die Anforderung verlangt, dass die titleauthor und-Metadaten für jedes Element zurückgegeben werden, aus dem ein Textauszug abgerufen wird. Die Antwort sollte maximal vier Dokumente enthalten.

Anforderung

Das folgende Beispiel zeigt die Antwort.

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Beispiel 6: Abrufen von Daten von Copilot-Connectors mithilfe bestimmter Verbindungs-IDs

Das folgende Beispiel zeigt eine Anforderung, die den Abruf von Copilot-Connectors auf bestimmte Verbindungs-IDs beschränkt. Die Anforderung verlangt, dass die titleauthor und-Metadaten für jedes Element zurückgegeben werden, aus dem ein Textauszug abgerufen wird. Die Antwort umfasst bis zu zehn Dokumente.

Anforderung

Das folgende Beispiel zeigt die Antwort.

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Beispiel 7: Verwenden von Filterausdrücken

Die folgenden Beispiele zeigen KQL-Ausdrücke, die Sie in der filterExpression Eigenschaft für bestimmte Szenarien verwenden können.

Filtern nach Copilot-Connectoreigenschaften

In diesem Beispiel Label_Title ist eine abfragbare Eigenschaft im ServiceNow Copilot-Connectorschema. Die Abfrage filtert nach Elementen, die in der Label_Title Eigenschaft enthalten sindCorporate VPN.

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

Filtern von `Author` SharePoint-Ergebnissen nach der Eigenschaft

In diesem Beispiel filtert die Abfrage nach Elementen mit Megan Bowen als Autorin.

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

SharePoint-Ergebnisse nach einem bestimmten Datumsbereich mithilfe der `LastModifiedTime` Eigenschaft filtern

In diesem Beispiel filtert die Abfrage nach Elementen, die zwischen dem 22. Juli 2024 und dem 8. Januar 2025 geändert wurden.

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

Filtern von SharePoint-Ergebnissen mithilfe der `FileExtension` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Dateien mit der Dateierweiterung .docx, .pdf oder .pptx.

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

Filtern von SharePoint-Ergebnissen mithilfe der `Filename` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Dateien mit dem Namen Contoso Mission Statement.docx.

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

Filtern von SharePoint-Ergebnissen mithilfe der `FileType` Eigenschaft

In diesem Beispiel filtert die Abfrage PDF-Dateien, PowerPoint-Präsentationen und Word-Dokumente.

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

Ermitteln der Vertraulichkeit von SharePoint-Ergebnissen durch Filtern mithilfe der `InformationProtectionLabelId` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Elementen mit einer bestimmten Information Protection-Bezeichnung.

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

Filtern von SharePoint-Ergebnissen mithilfe der `ModifiedBy` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Elementen, die von Adele Vance geändert wurden.

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

Filtern von SharePoint-Ergebnissen mithilfe der `SiteID` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Elementen von einer bestimmten SharePoint-Website.

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

Filtern von SharePoint-Ergebnissen mithilfe der `Title` Eigenschaft

In diesem Beispiel filtert die Abfrage nach Elementen mit Windows 10 Device im Titel.

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

Beispiel 8: Miniaturansichten für Extrakte einschließen

Das folgende Beispiel zeigt eine Anforderung, die die includeThumbnails Eigenschaft und die zugehörige Antwort hinzufügt, die Miniaturansichten und die zugehörigen Seitenzahlen enthält.

Anforderung

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
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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"
      }
    }
  ]
}

Feedback

War diese Seite hilfreich?

Last updated on 2026-08-20

Abrufen von Erdungsdaten

Berechtigungen

HTTP-Anforderung

Anforderungsheader

Anforderungstext

Antwort

Beispiele

Beispiel 1: Abrufen von Daten aus SharePoint

Anforderung

Antwort

Beispiel 2: Abrufen von Daten von Copilot-Connectors

Anforderung

Antwort

Beispiel 3: Batchanforderungen an die Retrieval-API

Anforderung

Antwort

Beispiel 4: Abrufen von Daten von einer bestimmten SharePoint-Website

Anforderung

Antwort

Beispiel 5: Abrufen von Daten von mehreren SharePoint-Websites

Anforderung

Antwort

Beispiel 6: Abrufen von Daten von Copilot-Connectors mithilfe bestimmter Verbindungs-IDs

Anforderung

Antwort

Beispiel 7: Verwenden von Filterausdrücken

Filtern nach Copilot-Connectoreigenschaften

Filtern von Author SharePoint-Ergebnissen nach der Eigenschaft

SharePoint-Ergebnisse nach einem bestimmten Datumsbereich mithilfe der LastModifiedTime Eigenschaft filtern

Filtern von SharePoint-Ergebnissen mithilfe der FileExtension Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der Filename Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der FileType Eigenschaft

Ermitteln der Vertraulichkeit von SharePoint-Ergebnissen durch Filtern mithilfe der InformationProtectionLabelId Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der ModifiedBy Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der SiteID Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der Title Eigenschaft

Beispiel 8: Miniaturansichten für Extrakte einschließen

Anforderung

Antwort

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen

Filtern von `Author` SharePoint-Ergebnissen nach der Eigenschaft

SharePoint-Ergebnisse nach einem bestimmten Datumsbereich mithilfe der `LastModifiedTime` Eigenschaft filtern

Filtern von SharePoint-Ergebnissen mithilfe der `FileExtension` Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der `Filename` Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der `FileType` Eigenschaft

Ermitteln der Vertraulichkeit von SharePoint-Ergebnissen durch Filtern mithilfe der `InformationProtectionLabelId` Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der `ModifiedBy` Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der `SiteID` Eigenschaft

Filtern von SharePoint-Ergebnissen mithilfe der `Title` Eigenschaft