Web API-Servicedokumente

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.

$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"

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.

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

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.

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.

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