Documentos de servicio de la API web

Artículo
02/01/2024

Los extremos de OData proporcionan documentos de servicio que describen las funciones del servicio. Comprender estos documentos de servicio le ayuda a utilizar los recursos que están disponibles en el entorno en el que está trabajando.

Documento de servicio

Realice una solicitud GET en el extremo de la API web para ver el documento de servicio para su entorno.

El extremo de la API web tiene un aspecto similar al siguiente: https://yourorg.api.crm.dynamics.com/api/data/v9.2/. Esta parte: yourorg.api.crm, depende de su entorno. Consulte Ver recursos para desarrolladores para saber cómo encontrarlo.

Si está utilizando Insomnia con la configuración de entorno recomendada, simplemente use la variable de entorno _.webapiurl.

Si ha instalado los Requisitos previos para Inicio rápido de API web con PowerShell y Visual Studio Code, puede ver el documento de servicio en Visual Studio Code usando este script de PowerShell después de editar la variable $environmentUrl.

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

Si esto no funciona, consulte los pasos Solución de problemas en Inicio rápido de API web con PowerShell y Visual Studio Code

Debería ver resultados como este:

{
    "@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"
        },
    ...

El documento de servicio proporciona una lista de todos los EntitySets disponibles en su entorno. Un EntitySet es el nombre de un recurso que hace referencia a una tabla en Dataverse. Utilizará el nombre del conjunto de entidades en la URL para realizar operaciones en los datos de una tabla específica.

Sugerencia

Use Ctrl+F en los resultados de este documento para encontrar el nombre correcto del conjunto de entidades.

Nombre del conjunto de entidades

Utilice siempre el nombre del conjunto de entidades en lugar del nombre de la colección lógica. De forma predeterminada, el nombre del conjunto de entidades coincide con el valor de propiedad de la tabla EntityMetadata.LogicalCollectionName, pero no debería depender de esto.

Cambiar el nombre de un conjunto de entidades

Si tiene una tabla personalizada a la que desea dirigirse con otro nombre de conjunto de entidades, puede actualizar el valor de propiedad de la tabla EntityMetadata.EntitySetName para usar un nombre distinto. Obtenga más información sobre las propiedades de la tabla que puede cambiar

Importante

Solo debe cambiar el EntitySetName de una tabla cuando la crea y antes de que se escriba cualquier código usando la tabla. Romperá cualquier código que use el nombre anterior.

Documento $metadata de CSDL

Adjuntar $metadata al extremo de la API web para recuperar el documento $metadata de Common Schema Definition Language (CSDL).

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

Este documento XML describe todas las tablas y operaciones que puede utilizar en su entorno.

Puede descargar el documento CSDL $metadata usando Visual Studio Code y Powershell con estas instrucciones.

Importante

Este documento es el origen central para todo lo relacionado con la API web. Se recomienda hacer referencia al mismo con frecuencia. Use Ctrl+F en este documento para ubicar las EntityType, Action, Function, ComplexType, o EnumType específicas que utilizará. Los nombres distinguen mayúsculas de minúsculas.

Anotaciones de metadatos

Para obtener aún más información de $metadata, agregue ?annotations=true a la URL.

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

Al establecer esete parámetro se incluyen muchos tipos diferentes de anotaciones que pueden ser útiles. La mayoría de las anotaciones no se incluyen de forma predeterminada porque aumentan el tamaño total del documento.

Estas anotaciones también se pueden devolver agregando el encabezado de solicitud Prefer: odata.include-annotations="*". Este encabezado de solicitud también funciona para otros tipos de solicitudes. El parámetro de consulta annotations=true solo funciona para el documento $metadata.

Espacio de nombres de servicio

Cerca de la parte superior del documento $metadata, encontrará este elemento XML:

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

Este elemento le informa que todos los elementos en el servicio que están dentro del espacio de nobmres Microsoft.Dynamics.CRM y que mscrm es el alias para el espacio de nombres. En algunas situaciones, deberá usar el nombre completo de un objeto, por lo que será necesario usar el valor del espacio de nombres.

Pasos siguientes

Información sobre tipos de entidades.

Tipos de entidad

Consulte también

Tipos y operaciones de API web
Tipos de entidad de la API web
Propiedades de API web
Propiedades de navegación de la API web
Acciones de la API web
Funciones de la API web
Tipos complejos y de enumeración de API web
Usar la API web de Dataverse

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Compartir a través de