Web API-Servicedokumente

Artikel
02/01/2024

OData-Endpunkte stellen Dienstdokumente bereit, die die Funktionen des Dienstes beschreiben. Das Verständnis dieser Service-Dokumente hilft Ihnen, die Ressourcen zu nutzen, die in der Umgebung, mit der Sie arbeiten, zur Verfügung stehen.

Servicedokument

Führen Sie eine GET-Anfrage am Web-API-Endpunkt durch, um das Dienstdokument für Ihre Umgebung zu sehen.

Ihr Web-API-Endpunkt sieht in etwa so aus: https://yourorg.api.crm.dynamics.com/api/data/v9.2/. Der Teil yourorg.api.crm hängt von Ihrer Umgebung ab. Unter Entwicklerressourcen anzeigen erfahren Sie, wie Sie ihn finden.

Wenn Sie Insomnia mit den empfohlenen Umgebungseinstellungen verwenden, verwenden Sie einfach die _.webapiurl-Umgebungsvariable.

Wenn Sie die Voraussetzungen für Schnellstart-Web-API mit PowerShell und Visual Studio Code installiert haben, können Sie das Dienstdokument im Visual Studio Code mit diesem PowerShell-Skript anzeigen, nachdem Sie die $environmentUrl-Variable bearbeitet haben.

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## <a name="login-if-not-already-logged-in"></a>Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}
# <a name="get-an-access-token"></a>Get an access token
$token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
# <a name="common-headers"></a>Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# <a name="view-service-document"></a>View service document
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/') -Method 'Get' -Headers $baseHeaders
| ConvertTo-Json | Out-File -FilePath "service-document.json"
code "service-document.json"

Wenn dies nicht funktioniert, sehen Sie sich die Schritte zur Problembehandlung in Schnellstart-Web-API mit PowerShell und Visual Studio Code an

Sie sollten Ergebnisse wie diese sehen:

{
    "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
    ...

Das Servicedokument enthält eine Liste aller EntitySets, die in Ihrer Umgebung verfügbar sind. Ein Entitätsset ist der Name einer Ressource, die auf eine Tabelle in Dataverse verweist. Sie werden den Namen des Entity Sets in der URL verwenden, um Vorgänge mit den Daten einer bestimmten Tabelle durchzuführen.

Tipp

Verwenden Sie Strg + F mit den Ergebnissen dieses Dokuments, um den richtigen Namen des Entitätssatzes zu finden.

Entitätssatzname

Verwenden Sie immer den Namen des Entitätssatzes und nicht den Namen der logischen Sammlung. Standardmäßig stimmt der Entitätssatzname mit der Tabelle EntityMetadata.LogicalCollectionName überein, Sie sollten sich aber nicht darauf verlassen.

Den Entitätssatznamen ändern

Wenn Sie eine benutzerdefinierte Tabelle haben, die Sie mit einem anderen Entitätssatznamen ansprechen möchten, können Sie den EntityMetadata.EntitySetName-Eigenschaftswert der Tabelle aktualisieren, um einen anderen Namen zu verwenden. Erfahren Sie mehr über Tabelleneigenschaften, die Sie ändern können

Wichtig

Sie sollten den EntitySetName einer Tabelle nur ändern, wenn Sie sie erstellen und bevor Code unter Verwendung der Tabelle geschrieben wird. Dadurch wird jeder Code beschädigt, der den alten Namen verwendet hat.

CSDL-$metadata-Dokument

Hängen Sie $metadata an den Web-API Endpunkt an, um das $metadata-Dokument der Common Schema Definition Language (CSDL) abzurufen.

Beispiel: https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata

Dieses XML-Dokument beschreibt alle Tabellen und Vorgänge, die Sie in Ihrer Umgebung verwenden können.

Sie können mithilfe dieser Anweisungen das CSDL-$metadata-Dokument mit Visual Studio Code und Powershell herunterladen.

Wichtig

Dieses Dokument ist die Quelle der Wahrheit für alles, was mit Web-API zu tun hat. Sie werden häufig darauf verweisen wollen. Verwenden Sie Ctrl+F mit diesem Dokument, um den/die jeweilige(n) EntityType, Action, Function, ComplexType oder EnumType zu suchen, den/die verwenden werden. Bei den Namen wird die Groß-/Kleinschreibung beachtet.

Metadatenanmerkungen

Um noch mehr Informationen aus den $metadata zu erhalten, hängen Sie ?annotations=true an die URL an.

Beispiel: https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata?annotations=true

Wenn Sie diesen Parameter einstellen, können Sie viele verschiedene Arten von Anmerkungen hinzufügen, die nützlich sein können. Die meisten Anmerkungen sind standardmäßig nicht enthalten, da sie die Gesamtgröße des Dokuments erhöhen.

Diese Anmerkungen können auch durch Hinzufügen des Prefer: odata.include-annotations="*"-Anforderungsheaders zurückgegeben werden. Dieser Anforderungsheader funktioniert auch für andere Arten von Anforderungen. Der Abfrageparameter annotations=true funktioniert nur für das $metadata-Dokument.

Servicenamespace

Ganz oben in den $metadaten finden Sie dieses XML-Element:

    <edmx:DataServices>
        <Schema Namespace="Microsoft.Dynamics.CRM" Alias="mscrm" xmlns="http://docs.oasis-open.org/odata/ns/edm">

Dieses Element informiert Sie darüber, dass alle Artikel des Dienstes im Namensraum Microsoft.Dynamics.CRM liegen und dass mscrm der Alias für den Namensraum ist. In manchen Situationen müssen Sie den vollständig qualifizierten Namen eines Objekts verwenden, sodass Sie den Namespace-Wert verwenden müssen.

Nächste Schritte,

Informationen zu Entitätstypen.

Entitätstypen

Siehe auch

Internet API-Typen und -Vorgänge
Web-API Entitätstypen
Web-API-Eigenschaften
Web-API Navigationseigenschaften
Web-API-Aktionen
Web-API-Funktionen
Web-API komplexe Typen und Aufzählungstypen
Verwenden der Dataverse-Web-API

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).