Freigeben über

Ausführen der Suche mithilfe der Microsoft 365 Copilot Search-API

Wichtig

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

Führen Sie eine hybride (semantische und lexikalische) Suche in OneDrive für Arbeits- oder Schulinhalte durch, indem Sie Abfragen in natürlicher Sprache mit kontextbezogenem Verständnis verwenden. Ermitteln Sie relevante Dokumente und Dateien, auf die Sie Zugriff haben, und beachten Sie dabei die definierten Zugriffssteuerungen innerhalb der organization. Versuchen Sie, Ihre erste Abfrage an die Microsoft 365 Copilot-Such-API auszugeben. Erfahren Sie, wie Sie bis zu 20 Anforderungen an die Such-API batchen können.

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. Für den Zugriff auf Daten aus OneDrive für die Geschäfts-, Schul- oder Unidatenquelle benötigen Sie Die Berechtigungen Files.Read.All oder Files.ReadWrite.All. Außerdem benötigen Sie die Berechtigungen Sites.Read.All oder Sites.ReadWrite.All.

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

HTTP-Anforderung

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

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 Parameter aufgeführt, die beim Aufrufen dieser Aktion erforderlich sind.

Parameter Typ Beschreibung
query Zeichenfolge Abfrage in natürlicher Sprache zum Suchen nach relevanten Dateien. Maximal 1.500 Zeichen. Erforderlich.
pageSize Int32 Anzahl der pro Seite zurückgegebenen Ergebnisse (1-100). Standardwert: 25. Optional.
dataSources copilotSearchDataSourcesConfiguration Konfiguration für Datenquellen, die in die Suche einbezogen werden sollen. Optional.

Antwort

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

Beispiele

Beispiel 1: Einfache Suchanforderung

Das folgende Beispiel zeigt die mindestens erforderlichen Parameter, um eine hybride Suche (semantisch und lexikalisch) in OneDrive für Geschäfts-, Schul- oder Uniinhalte durchzuführen.

Anforderung

Das folgende Beispiel zeigt die Antwort. Probieren Sie dieses Beispiel mit Graph Explorer aus.

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

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

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

Beispiel 2: Suche mit Filterung und Metadaten

Das folgende Beispiel zeigt eine Anforderung mit einer bestimmten OneDrive-Pfadfilterung und Metadatensammlung. Die Anforderung fordert die Rückgabe der title Metadaten und author für jedes Suchergebnis auf.

Anforderung

Das folgende Beispiel zeigt die Antwort. Probieren Sie dieses Beispiel mit Graph Explorer aus.

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

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

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

Beispiel 3: Suche mit pfadbasierter Filterung

Das folgende Beispiel zeigt, wie Sie in bestimmten OneDrive-Pfaden mithilfe von Keyword Query Language (KQL)-Pfadausdrücken suchen.

Anforderung

Das folgende Beispiel zeigt die Antwort. Probieren Sie dieses Beispiel mit Graph Explorer aus.

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

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

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

Beispiel 4: Batchanforderungen an die Such-API

Das folgende Beispiel zeigt, wie Anforderungen an die Such-API in Batches gesendet werden. Die Such-API unterstützt bis zu 20 Anforderungen pro Batch. Der id in der Anforderungsnutzlast muss eine Zeichenfolge sein, die jede Anforderung im Batch eindeutig identifiziert.

Anforderung

Das folgende Beispiel zeigt die Antwort. Probieren Sie dieses Beispiel mit Graph Explorer aus.

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

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

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

Verwandte Inhalte

  • Last updated on