Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
[Dieser Artikel ist eine Vorabdokumentation und kann geändert werden.]
Semantische Dataverse-Modelle definieren die Dataverse-Tabellen, die zur Beantwortung natürlichsprachlicher Fragen verfügbar sind. In diesem Artikel wird erläutert, wie Sie diese Modelle mithilfe der Dataverse Ask-APIs auflisten, erstellen und löschen, wodurch Sie verwalten können, welche Tabellen Ihre Anwendung abfragen kann.
Wichtig
- Dies ist eine Vorschauversion.
- Vorschauangebote werden as-is 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.
- Vorschaufunktionen 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 APIs verwenden, führen Sie die Schritte in "Erste Schritte mit den Dataverse Ask-APIs" aus.
Ersetzen Sie [Organization URI] durch den Organisations-URI, wie z. B. https://contoso.api.crm.dynamics.com.
Auswählen von Tabellen für ein semantisches Modell
Verwenden Sie logische Tabellennamen wie account, contact und opportunity. Verwenden Sie keine Anzeigenamen, Entitätssatznamen oder Sammlungsnamen.
Wählen Sie nur Tabellen aus, die für die Fragen relevant sind, die Ihre Anwendung beantworten muss. Die Identität, die eine Ask-Anforderung sendet, muss Lesezugriff auf die ausgewählten Tabellen, Spalten und Datensätze haben.
Auflisten semantischer Modelle
Der Listenvorgang gibt semantische Modelle zurück, die in der aktuellen Dataverse-Umgebung verfügbar sind.
GET [Organization URI]/api/iq/v1.0/semanticmodel HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
Eine erfolgreiche Anfrage gibt Folgendes zurück:200 OK
{
"data": [
{
"id": "00000000-0000-0000-0000-000000000001",
"uniqueName": "Sales pipeline",
"source": "SemanticModelAPI",
"description": "This is a test semantic model for demo purpose",
"tables": [
"account",
"opportunity"
],
"createdBy": "Adele Vance",
"modifiedOn": "2026-08-17T20:00:00Z",
"createdOn": "2026-08-15T17:30:00Z",
"ownerId": "00000000-0000-0000-0000-000000000002",
"owner": "Adele Vance"
}
]
}
Verlassen Sie sich nicht auf die Reihenfolge im Array. Suchen Sie ein Modell anhand der genauen uniqueName oder id.
Eigenschaften des semantischen Modells
| Name | Typ | Nullfähig | Beschreibung |
|---|---|---|---|
id |
Zeichenfolge (GUID) | Yes | Der eindeutige Bezeichner des semantischen Modells. |
uniqueName |
Schnur | Yes | Der eindeutige Name des Semantikmodells. |
tables |
Array von Zeichenfolgen | Yes | Logische Namen der zugeordneten Dataverse-Tabellen. |
createdBy |
Schnur | Yes | Der vollständige Name des Benutzers, der das Semantikmodell erstellt hat. |
modifiedOn |
Zeichenfolge (Datum/Uhrzeit) | Yes | Das UTC-Datum und die Uhrzeit der letzten Änderung des semantischen Modells. |
createdOn |
Zeichenfolge (Datum/Uhrzeit) | Yes | Das UTC-Datum und die Uhrzeit der Erstellung des semantischen Modells. |
ownerId |
Zeichenfolge (GUID) | Yes | Der eindeutige Bezeichner des Semantikmodellbesitzers. |
owner |
Schnur | Yes | Vollständiger Name des Benutzers, der dieses Semantikmodell besitzt. |
source |
Schnur | Yes | Identifiziert den Kanal, der das Semantikmodell erstellt hat. |
description |
Schnur | Yes | Beschreibung dieses semantischen Modells. |
Ein semantisches Modell erstellen
Der Erstellungsvorgang ordnet einem oder mehreren Dataverse-Tabellen einen eindeutigen Namen zu.
POST [Organization URI]/api/iq/v1.0/semanticmodel HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
Content-Type: application/json
{
"uniqueName": "Sales pipeline",
"tables": [
"account",
"opportunity"
]
}
Anforderungseigenschaften
| Name | Typ | Required | Beschreibung |
|---|---|---|---|
uniqueName |
Schnur | Yes | Der eindeutige Name des zu erstellenden Semantikmodells. |
tables |
Array von Zeichenfolgen | Yes | Eine oder mehrere logische Namen der Dataverse-Tabelle, die dem Modell zugeordnet werden sollen. |
Eine erfolgreiche Anfrage gibt Folgendes zurück:201 Created
{
"data": {
"id": "00000000-0000-0000-0000-000000000001",
"uniqueName": "Sales pipeline",
"createdOn": "2026-08-17T20:00:00Z"
},
"message": "Semantic model created successfully"
}
| Name | Typ | Nullfähig | Beschreibung |
|---|---|---|---|
data.id |
Zeichenfolge (GUID) | Yes | Der eindeutige Bezeichner des erstellten Semantikmodells. |
data.uniqueName |
Schnur | Yes | Der eindeutige Name des erstellten Semantikmodells. |
data.createdOn |
Zeichenfolge (Datum/Uhrzeit) | No | Das UTC-Datum und die Uhrzeit der Erstellung des semantischen Modells. |
message |
Schnur | Yes | Eine Meldung, die das Ergebnis des Vorgangs beschreibt. |
Speichern Sie id , wenn Ihre Anwendung das Modell später löschen muss. Verwenden Sie uniqueName als den Wert semanticModelName in einer Ask-Anfrage.
Semantische Modellnamen müssen in einer Umgebung eindeutig sein. Wenn eine Anforderung aufgrund eines Netzwerk- oder vorübergehenden Fehlers unsicher ist, führen Sie die Semantikmodelle auf, bevor sie erneut gesendet werden.
Löschen eines semantischen Modells
Der Löschvorgang verwendet das semantische Modell id, nicht den Namen.
Suchen Sie vor dem Löschen eines Semantikmodells die Apps und Agents, die es verwenden, um die Auswirkungen zu bewerten.
Wichtig
Sie können nur semantische Modelle löschen, die Sie mithilfe des Create-Vorgangs erstellt haben. Sie können semantische Modelle, die einem App-Modul, Bot oder Agent zugeordnet sind, nicht mithilfe dieser API löschen.
DELETE [Organization URI]/api/iq/v1.0/semanticmodel/00000000-0000-0000-0000-000000000001 HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
| Name | Typ | Beschreibung |
|---|---|---|
id |
Zeichenfolge (GUID) | Der eindeutige Bezeichner des zu löschenden Semantikmodells. |
Eine erfolgreiche Anfrage gibt Folgendes zurück:200 OK
{
"data": {
"id": "00000000-0000-0000-0000-000000000001"
},
"message": "Semantic model deleted successfully"
}
| Name | Typ | Nullfähig | Beschreibung |
|---|---|---|---|
data.id |
Zeichenfolge (GUID) | Yes | Der eindeutige Bezeichner des gelöschten Semantikmodells. |
message |
Schnur | Yes | Eine Meldung, die das Ergebnis des Vorgangs beschreibt. |
Nach dem Löschen können Anwendungen den Modellnamen in Ask-Anforderungen nicht mehr verwenden.
Suchen von Apps und Agents, die ein Semantikmodell verwenden
Verwenden Sie den optionalen include=botinfo Abfrageparameter, um App-Module, Bot-Komponenten und Agents zu identifizieren, die jedes semantische Modell verwenden. Verwenden Sie diese Informationen, um Abhängigkeiten zu bewerten, bevor Sie ein semantisches Modell ändern oder löschen oder untersuchen, auf welche Anwendungen und Agents darauf verweisen.
Bei dem botinfo-Wert wird die Groß-/Kleinschreibung nicht beachtet. Der include Parameter akzeptiert eine durch Trennzeichen getrennte Liste von Werten.
GET [Organization URI]/api/iq/v1.0/semanticmodel?include=botinfo HTTP/1.1
Authorization: Bearer <access token>
Accept: application/json
Eine erfolgreiche Anfrage gibt Folgendes zurück:200 OK
{
"data": [
{
"id": "00000000-0000-0000-0000-000000000003",
"uniqueName": "Sales pipeline",
"source": "SemanticModelAPI",
"description": "This is a test semantic model for demo purpose",
"tables": [
"lead",
"product"
],
"createdBy": "Adele Vance",
"modifiedOn": "2026-08-17T20:00:00Z",
"createdOn": "2026-08-15T17:30:00Z",
"ownerId": "00000000-0000-0000-0000-000000000004",
"owner": "Adele Vance",
"m365AppModuleId": "00000000-0000-0000-0000-000000000005",
"appModulePrimaryName": "Customer Service Hub",
"appModulePrimaryUniqueName": "Customerservicehub",
"m365AppModuleIdSecondary": "00000000-0000-0000-0000-000000000006",
"appModuleSecondaryName": "Power Pages Management",
"appModuleSecondaryUniqueName": "mspp_PowerPageManagement",
"bots": [
{
"botComponentName": "SalesSpecificQnA",
"agentName": "Copilot in Dynamics 365 Sales"
}
]
}
]
}
Zusätzliche App- und Agent-Eigenschaften
| Name | Typ | Nullfähig | Beschreibung |
|---|---|---|---|
m365AppModuleId |
Schnur | Yes | ID der modellgesteuerten App, die einem ALM-kompatiblen primären Semantikmodell zugeordnet ist. Dieser Wert basiert auf einer Dataverse-Lookupbeziehung mit dem App-Modul. |
m365AppModuleIdSecondary |
Schnur | Yes | App-Modul-ID, die einem sekundären Semantikmodell zugeordnet ist. Dieser Wert wird als GUID gespeichert und erstellt keine ALM-verwaltete Beziehung zum App-Modul. |
appModulePrimaryName |
Schnur | Yes | Anzeigename des von m365AppModuleId referenzierten App-Moduls. |
appModulePrimaryUniqueName |
Schnur | Yes | Logischer Name des App-Moduls, auf das verwiesen wird.m365AppModuleId |
appModuleSecondaryName |
Schnur | Yes | Anzeigename des App-Moduls, deren ID in m365AppModuleIdSecondary gespeichert ist. |
appModuleSecondaryUniqueName |
Schnur | Yes | Logischer Name des App-Moduls, dessen ID in m365AppModuleIdSecondary gespeichert ist. |
bots |
Objekt-Array | Yes | Bot-Komponenten und -Agents, die das semantische Modell verwenden. |
botComponentName |
Schnur | Yes | Anzeigename einer Botkomponente, die das semantische Modell verwendet oder referenziert. Wird in der bots-Sammlung zurückgegeben. |
agentName |
Schnur | Yes | Anzeigename des Agenten, der die Botkomponente enthält. Wird in der bots-Sammlung zurückgegeben. |
Optimieren eines semantischen Modells
Nachdem Sie das semantische Modell erstellt haben, können Sie es auf der Semantikmodellseite in Power Apps optimieren:
Signale: Schalten Sie systeminterne abgeleitete Signaltypen, z. B. Tabellenzusammenfassungen oder Formularzusammenfassungen, in allen Tabellen ein oder aus. Sie können auch Tabellen ausschließen, die vertrauliche oder irrelevante Daten enthalten, und einzelne Ansichten oder Beziehungen deaktivieren, die veraltet oder irreführend sind. Weitere Informationen finden Sie unter Feinabstimmung von Semantikmodellsignalen.
Glossar: Fügen Sie Geschäftsvokabular hinzu, das das System nicht ableiten kann, z. B. Akronyme oder organisationsspezifische Ausdrücke, sodass Agenten Benutzerfragen richtig interpretieren können. Weitere Informationen finden Sie unter Verwalten von Glossareinträgen für semantische Modelle.
Aktualisierung: Das semantische Modell wird automatisch alle 12 Stunden neu generiert. Um Ihre Änderungen sofort anzuwenden, lösen Sie eine manuelle Regeneration aus. Weitere Informationen finden Sie unter "Neuerieren des semantischen Modells".