Freigeben über

Abrufen von Erdungsdaten

Wichtig

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

Die Microsoft 365 Copilot Abruf-API ermöglicht das Abrufen relevanter Textextrakte aus SharePoint-, OneDrive- und Copilot-Connectorsinhalten, auf die der aufrufende Benutzer Zugriff hat, wobei die definierten Zugriffssteuerungen innerhalb des Mandanten beachtet werden. Verwenden Sie die Abruf-API, um Ihre generativen KI-Lösungen mit Microsoft 365-Daten zu grounden und gleichzeitig kontextbezogene Rückrufe 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

* Sie benötigen sowohl die Berechtigungen Files.Read.All als auch Sites.Read.All, um SharePoint- und OneDrive-Inhalte abzurufen.

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 Textextrakte verwendet wird. Für diesen Parameter sind maximal 1.500 Zeichen zulässig. Ihre queryString sollte ein einzelner Satz sein, 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, oneDriveBusinessund externalItem. Erforderlich.
dataSourceConfiguration dataSourceConfiguration Enthält zusätzliche Konfigurationsinformationen für anwendbare Datenquellen. dataSourceConfiguration enthält ein Objekt namens externalItem, in dem Sie den Abruf von Copilot-Connectors konfigurieren können. Optional.
filterExpression Zeichenfolge Keyword Query Language-Ausdruck (KQL) mit abfragbaren Eigenschaften und Attributen von SharePoint-, OneDrive- oder Copilot-Connectors, um den Abruf vor der Ausführung der Abfrage zu bebereichen. Sie können ggf. die Ungleichheitsoperatoren , OR, NOTund verwendenAND, wenn Sie Ihre filterExpressionerstellen. Unterstützte SharePoint- und OneDrive-Eigenschaften zum Filtern sind: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, PathSiteIDLastModifiedTimeModifiedByund .Title Beim Filtern nach Inhalten von Copilot-Connectors können Sie jede Eigenschaft verwenden, die im Copilot-Connectorschema als abfragbar gekennzeichnet ist. Wenn Sie mit dem Schema ihres gewünschten Copilot-Connectors nicht vertraut sind oder nicht wissen, welche Eigenschaften als abfragbar gekennzeichnet sind, wenden Sie sich an den Administrator oder Entwickler, der den gewünschten Copilot-Connector konfiguriert hat. Microsoft wird keine Probleme beim Filtern nach Eigenschaften von SharePoint- und Copilot-Connectors beheben, die hier nicht erwähnt werden. Sie können beim Erstellen von filterExpressionmehrere Eigenschaften und Operatoren verwenden. Standardmäßig wird kein Bereich 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 ob keine filterExpressionvorhanden wäre. 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. Nur abrufbare Metadateneigenschaften können in diese Liste aufgenommen werden. 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 sein. Standardmäßig gibt bis zu 25 Ergebnisse zurück. Optional.

Antwort

Wenn die Aktion erfolgreich verläuft, werden der 200 OK Antwortcode und ein retrievalResponse-Element im Antworttext zurückgegeben.

Beispiele

Beispiel 1: Abrufen von Daten aus SharePoint

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten aus SharePoint. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Element auf, aus dem eine Textextraktion abgerufen wird. Die Antwort enthält 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": "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 aus Copilot-Connectors

Das folgende Beispiel zeigt eine Anforderung zum Abrufen von Daten von Copilot-Connectors. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Element auf, aus dem eine Textextraktion abgerufen wird. Die Antwort enthält 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 Abruf-API

Im folgenden Beispiel wird gezeigt, wie Anforderungen an die Abruf-API in Batches gesendet werden. Die Abruf-API unterstützt bis zu 20 Anforderungen pro Batch. 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 zum Standort an. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Element auf, aus dem eine Textextraktion 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/\"",
  "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 Standorten an. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Element auf, aus dem eine Textextraktion 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 aus Copilot-Connectors mithilfe bestimmter Verbindungs-IDs

Das folgende Beispiel zeigt eine Anforderung, die den Abruf von Copilot-Connectors auf bestimmte Verbindungs-IDs einschränkt. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Element auf, aus dem eine Textextraktion abgerufen wird. Die Antwort enthält 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",
  "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

Im Folgenden finden Sie Beispiele für KQL-Ausdrücke, die in der filterExpression -Eigenschaft für bestimmte Szenarien verwendet werden können.

Filtern nach Copilot-Connectoreigenschaften

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

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

Filtern von SharePoint-Ergebnissen nach der Author Eigenschaft

In diesem Beispiel wird die Abfrage nach Elementen mit Megan Bowen als Autor gefiltert.

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

Filtern von SharePoint-Ergebnissen nach einem bestimmten Datumsbereich mithilfe der LastModifiedTime -Eigenschaft

In diesem Beispiel wird die Abfrage nach Elementen gefiltert, 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 wird die Abfrage nach Dateien mit der dateierweiterung .docx, .pdf oder .pptx gefiltert.

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

Filtern von SharePoint-Ergebnissen mithilfe der Filename -Eigenschaft

In diesem Beispiel wird die Abfrage nach Dateien mit dem Namen Contoso Mission Statement.docxgefiltert.

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

Filtern von SharePoint-Ergebnissen mithilfe der FileType -Eigenschaft

In diesem Beispiel wird die Abfrage nach PDF-Dateien, PowerPoint-Präsentationen und Word Dokumenten gefiltert.

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

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

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

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

Filtern von SharePoint-Ergebnissen mithilfe der ModifiedBy -Eigenschaft

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

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

Filtern von SharePoint-Ergebnissen mithilfe der SiteID -Eigenschaft

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

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

Filtern von SharePoint-Ergebnissen mithilfe der Title -Eigenschaft

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

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

Verwandte Inhalte

  • Last updated on