Documentos del servicio API web

Los puntos de conexión de OData proporcionan documentos de servicio que describen las funcionalidades del servicio. Comprender estos documentos de servicio le ayudarán a usar los recursos disponibles en el entorno con 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 punto de conexión de 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 tu entorno. Consulte Ver recursos para desarrolladores para saber cómo encontrarlo.

Uso del insomnio

Si usa Insomnio con la configuración de entorno recomendada, solo tiene que usar la _.webapiurl variable de entorno.

Uso de PowerShell con Visual Studio Code

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

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}

# Get an access token
$secureToken = (Get-AzAccessToken `
   -ResourceUrl $environmentUrl `
   -AsSecureString).Token

# Convert the secure token to a string
$token = ConvertFrom-SecureString `
   -SecureString $secureToken `
   -AsPlainText


# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# 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 de solución de problemas de La API web de inicio rápido con PowerShell y Visual Studio Code.

Uso del explorador

Puede enviar GET solicitudes mediante el explorador. Escriba la dirección URL del punto de conexión de api web en la barra de direcciones del explorador.

Sugerencia

Instale una extensión del explorador para dar formato al JSON devuelto y facilitar la lectura, después, si usa Microsoft Edge, busque extensiones mediante formateador JSON.

Debería ver los resultados de esta manera:

{
    "@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. EntitySet es el nombre de un recurso que hace referencia a una tabla de Dataverse. Usará el nombre del conjunto de entidades en la dirección URL para realizar operaciones en los datos de una tabla específica.

Sugerencia

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

Nombre del conjunto de entidades

Use 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 la propiedad EntityMetadata.LogicalCollectionName , pero no debería depender de esto.

Cambio del nombre del conjunto de entidades

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

Importante

Solo debe cambiar el EntitySetName de una tabla al crearla y antes de que se escriba código mediante la tabla. Interrumpirá cualquier código que use el nombre anterior.

Documento de metadatos 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

En este documento XML se describen todas las tablas y operaciones que puede usar en su entorno.

Puede descargar el documento de $metadata CSDL mediante Visual Studio Code y PowerShell mediante estas instrucciones.

Importante

Este documento es el origen de la verdad para todo lo relacionado con la API web. Se recomienda hacer referencia al mismo con frecuencia. Use Ctrl+F en este documento para localizar el elemento específico EntityType, Action, Function, ComplexType o EnumType que usará. Los nombres son sensibles a mayúsculas y minúsculas.

Anotaciones de metadatos

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

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

Establecer este parámetro incluye 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 annotations=true parámetro de consulta solo funciona para el documento de $metadata.

Espacio de nombres de servicio

Cerca de la parte superior del $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 de que todos los elementos del servicio están dentro del Microsoft.Dynamics.CRM espacio de nombres y que mscrm es el alias del 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

Obtenga información sobre los tipos de entidad.

Tipos de entidad

Consulte también

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