Stellen Sie Fragen mithilfe eines Dataverse-Semantikmodells (Vorschau)

[Dieser Artikel ist eine Vorabdokumentation und kann geändert werden.]

Verwenden Sie den Ask-Vorgang mit einem Dataverse-Semantikmodell, um Fragen in natürlicher Sprache zu übermitteln. Der Vorgang gibt strukturierte Zeilen, eine Sprachzusammenfassung und Quelllinks zurück, wenn verfügbar.

Important

  • Dies ist eine Vorschauversion.
  • Vorschau-Angebote werden wie besehen bereitgestellt und können jederzeit geändert oder eingestellt werden. Bei nutzungsbasierten Diensten kann die Nutzung zugrunde liegender Anwendungsdienste während des Vorschauzeitraums weiterhin Lizenzgebühren verursachen.
  • Vorschaufeatures unterliegen ergänzenden Nutzungsbedingungen und stehen vor einer offiziellen Version zur Verfügung, damit Kunden frühzeitig Zugriff erhalten und Feedback geben können.

Bevor Sie diese API verwenden:

  1. Führen Sie die Schritte in "Erste Schritte" mit den Dataverse Ask-APIs aus.
  2. Erstellen Sie ein semantisches Modell.
  3. Gewähren Sie der aufrufenden Identität Lesezugriff auf die Tabellen, Spalten und Datensätze, die im semantischen Modell enthalten sind.

Ersetzen Sie [Organization URI] durch die Umgebungs-URL, z. B. https://contoso.api.crm.dynamics.com.

Senden Sie eine Ask-Anfrage

In diesem Beispiel wird eine Frage mithilfe eines semantischen Modells mit dem Namen Sales pipelinegestellt.

POST [Organization URI]/api/iq/v1.0/ask HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
Content-Type: application/json

{
  "query": "Which open opportunities have the highest estimated revenue?",
  "semanticModelName": "Sales pipeline",
  "searchMode": "Auto",
  "count": 100
}

Anforderungseigenschaften

Diese Eigenschaften enthalten die Informationen zu Ihrer Anforderung:

Name Typ Required Vorgabe Beschreibung
query Schnur Yes Nichts Die Frage der natürlichen Sprache, die beantwortet werden sollte.
semanticModelName Schnur Yes Nichts Das genaue uniqueName des zu verwendenden semantischen Modells.
searchMode SearchMode No Auto Die zu verwendende Suchstrategie.
count 32-Bit-Ganzzahl No 100 Die maximale Anzahl von Zeilen, die auf dieser Seite zurückgegeben werden sollen.
pagingToken Schnur No Null Ein undurchsichtiges Token aus einer vorherigen Antwort, das zum Abrufen der nächsten Seite verwendet wird.

SearchMode

Diese Werte geben die zu verwendende Suchstrategie an.

Wert Beschreibung
Auto Ermöglicht dem Dienst die Auswahl der Suchstrategie. Verwenden Sie diesen Wert, es sei denn, Ihr Szenario erfordert einen anderen Modus.
QuickResponse Favorisiert eine schnellere Antwort.
ThinkDeeper Bevorzugt eine tiefere Analyse, wenn die Frage länger dauern kann, um sie zu beantworten.

Der Suchmodus kann sich auf die Reaktionszeit auswirken. Anwendungen sollten ein geeignetes Clienttimeout festlegen und Statusfeedback für interaktive Benutzer bereitstellen.

Überprüfen Sie die Ask-Antwort

Eine erfolgreiche Anforderung gibt zurück 200 OK. Die Eigenschaften in den einzelnen rawResult Objekten hängen von der Frage ab:

{
  "rawResult": [
    {
      "opportunity": "Contoso renewal",
      "account": "Contoso",
      "estimatedRevenue": 125000
    }
  ],
  "citationLinks": [
    "[Organization URI]/main.aspx?pagetype=entityrecord&etn=opportunity&id=00000000-0000-0000-0000-000000000002"
  ],
  "summary": "The Contoso renewal has the highest estimated revenue.",
  "totalResultCount": 1,
  "pagingToken": null
}

Antworteigenschaften

Eine erfolgreiche Antwort enthält die folgenden Eigenschaften:

Name Typ Nullfähig Beschreibung
rawResult Objekt-Array Yes Zurückgegebene Zeilen für die Frage. Die Eigenschaften in den einzelnen Objekten hängen von der Frage und der generierten Abfrage ab.
citationLinks Array von Zeichenfolgen Yes Links zu Quellen, die der Antwort zugeordnet sind.
summary Schnur Yes Eine natürliche Sprachzusammenfassung des Ergebnisses.
totalResultCount 64-Bit-Ganzzahl No Die Gesamtzahl der übereinstimmenden Zeilen, wenn verfügbar. Dieser Wert kann nur die aktuelle Seite widerspiegeln.
pagingToken Schnur Yes Ein undurchsichtiges Token, das in einer nachfolgenden Anforderung übergeben werden soll, um die nächste Seite abzurufen.

Behandeln Sie rawResult als Array dynamischer JSON-Objekte. Zeigen Sie summary an, wenn es vorhanden ist, aber machen Sie die Verarbeitung der Zeilen nicht von ihm abhängig. Die Ergebnisse variieren mit den Dataverse-Berechtigungen des Aufrufers.

Abrufen der nächsten Seite

Wenn pagingToken, das in der Antwort zurückgegeben wird, nicht NULL ist, senden Sie eine weitere Anfrage mit derselben Frage, dem semantischen Modell, dem Suchmodus und der Anzahl. Kopieren Sie das Token genau:

POST [Organization URI]/api/iq/v1.0/ask HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
Content-Type: application/json

{
  "query": "Which open opportunities have the highest estimated revenue?",
  "semanticModelName": "Sales pipeline",
  "searchMode": "Auto",
  "count": 100,
  "pagingToken": "<paging-token-from-previous-response>"
}

Fahren Sie fort, bis die Antwort null oder leer pagingTokenzurückgibt. Decodieren, ändern oder konstruieren Sie keine Pagingtoken.

Dienstschutzgrenzwerte

Die Ask-API erzwingt niedrigere Grenzwerte, sodass Sie die allgemeinen Dataverse Service Protection API-Grenzwerte nicht erreichen. Sie verwalten diese Grenzwerte auf die gleiche Weise.

Die Ask-API ermöglicht jedem Benutzer, bis zu 30 Anforderungen pro Organisation pro Minute zu senden. Wenn Sie diesen Grenzwert überschreiten, gibt die API einen Fehler von 429 Zu viele Anforderungen zurück. Warten Sie auf den vom Retry-After Antwortheader angegebenen Zeitraum, bevor Sie weitere Anforderungen senden. Der Headerwert stellt die Anzahl der Sekunden dar, die gewartet werden sollen.

  • Zuletzt aktualisiert um