Uso de acciones de API web

Use acciones de API web para realizar operaciones reutilizables que tengan efectos secundarios en Microsoft Dataverse. Envíe una POST solicitud con acciones enumeradas en Web API Action Reference para modificar datos, desencadenar lógica de negocios o invocar procesos personalizados. También puede definir acciones personalizadas. Para obtener más información, vea Crear sus propios mensajes.

Las acciones se definen en el documento $metadata CSDL. Consulte Acciones de API web para obtener más información.

Acciones sin enlazar

El siguiente XML muestra la definición de la Merge acción representada en el documento de servicio $metadata.

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

La Merge acción corresponde a la MergeRequest clase cuando se usa el SDK para .NET. Use esta acción para combinar un par de registros duplicados. Esta acción no incluye un valor devuelto. Si se realiza correctamente, la operación se completa.

En el ejemplo siguiente se muestra la solicitud HTTP y la respuesta para ejecutar la acción Merge de dos registros de cuenta.

Solicitud:

POST [Organization URI]/api/data/v9.2/Merge HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

Respuesta:

HTTP/1.1 204 No Content
OData-Version: 4.0

Para obtener más información, consulte Combinar filas de tabla mediante la API web.

Acciones vinculadas

Puede enlazar una acción a una entidad o a una colección de entidades. Enlazar una acción a una entidad es más común.

En el documento $metadata CSDL, un Action elemento que representa una acción enlazada tiene un IsBound atributo establecido en true. El primer Parameter elemento definido dentro de la acción representa la entidad a la que está enlazada la operación. Cuando el Type atributo del parámetro es una colección, la operación se enlaza a una colección de entidades.

Al invocar una función enlazada, incluya el nombre completo de la función, junto con el espacio de nombres Microsoft.Dynamics.CRM. Si no incluye el nombre completo, obtendrá el siguiente error: Status Code:400 Request message has unresolved parameters.

Acciones enlazadas a una tabla

En el siguiente ejemplo se muestra la definición de la acción AddToQueue y el tipo complejo AddToQueueResponse en el CSDL como una acción enlazada a una entidad.

<ComplexType Name="AddToQueueResponse">
     <Property Name="QueueItemId" 
        Type="Edm.Guid" 
        Nullable="false" />
</ComplexType>
 <Action Name="AddToQueue" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.queue" 
    Nullable="false" />
  <Parameter Name="Target" 
    Type="mscrm.crmbaseentity" 
    Nullable="false" />
  <Parameter Name="SourceQueue" 
    Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" 
    Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" 
    Nullable="false" />
</Action>

Esta acción enlazada a la entidad es equivalente a la AddToQueueRequest usada por el SDK para .NET. En la API web, esta acción está enlazada al queue tipo de entidad que representa la AddToQueueRequest.DestinationQueueId propiedad.

Esta acción acepta varios parámetros más y devuelve un AddToQueueResponse tipo complejo correspondiente al AddToQueueResponse devuelto por el SDK para .NET. Cuando una acción devuelve un tipo complejo, la definición del tipo complejo aparece directamente encima de la acción en el CSDL.

Debe invocar una acción enlazada a una entidad mediante un URI para establecer el primer valor de parámetro. No se puede establecer como un valor de parámetro con nombre.

En el ejemplo siguiente se muestra cómo usar la AddToQueue acción para agregar una letra a una cola. Dado que el tipo del parámetro Target no es específico (mscrm.crmbaseentity), debe declarar explícitamente el tipo del objeto utilizando la propiedad @odata.type con el nombre completo del tipo de la entidad, incluido el espacio de nombres Microsoft.Dynamics.CRM. En este caso, Microsoft.Dynamics.CRM.letter. Para obtener más información, vea Especificar el tipo de parámetro de entidad.

Solicitud:

POST [Organization URI]/api/data/v9.2/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

Respuesta:


HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Acciones enlazadas a una colección de tablas

Es menos común buscar acciones enlazadas a una colección de entidades. En la lista siguiente se incluyen algunas acciones que puede encontrar:

FulfillSalesOrder en Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Como ejemplo de una acción enlazada a una colección de entidades, la siguiente definición muestra la ExportTranslation acción representada en el $metadata CSDL:

<ComplexType Name="ExportTranslationResponse">
   <Property Name="ExportTranslationFile" 
    Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" 
    IsBound="true">
   <Parameter Name="entityset" 
    Type="Collection(mscrm.solution)" 
    Nullable="false" />
   <Parameter Name="SolutionName" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
   <ReturnType Type="mscrm.ExportTranslationResponse" 
    Nullable="false" />
</Action>

Esta acción enlazada a la colección de entidades es equivalente a la ExportTranslationRequest usada por el SDK para .NET. En la API web, esta acción está enlazada al tipo de solution entidad. Pero en lugar de pasar un valor a la solicitud, la restricción de enlace de colección de entidades requiere que el URI de la solicitud incluya la ruta de acceso al conjunto de entidades especificado.

En el ejemplo siguiente se muestra cómo usar la ExportTranslation acción , que exporta un archivo binario que contiene datos sobre valores de cadena localizables que puede actualizar para modificar o agregar valores localizables. Observe cómo la acción vinculada a la colección de entidades aparece después del nombre del conjunto de entidades para la entidad de solución: solutions.

Solicitud:

POST [Organization URI]/api/data/v9.2/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Utilizar una acción personalizada

Una acción personalizada puede ser una API personalizada o una acción de proceso personalizada. Cada tipo de acción personalizada tiene una operación correspondiente que puede usar. Para una API personalizada, la operación puede ser una función. Para más información, consulte Creación de sus propios mensajes.

En el ejemplo siguiente se muestra una acción de proceso personalizada.

Ejemplo de acción personalizada: Agregar una nota a un contacto

Supongamos que desea crear una acción personalizada que agregue una nueva nota a un contacto específico. Puede crear una acción personalizada enlazada a la entidad contacto con las siguientes propiedades.

Etiqueta de interfaz de usuario	Importancia
Nombre del proceso	AñadirNotaAlContacto
Nombre único	new_AddNoteToContact
Entidad	Contacto
Categoría	Acción

Argumentos de proceso

Nombre	Tipo	Obligatorio	Dirección
Título de Nota	String	Obligatorio	Input
NoteText	String	Obligatorio	Input
NoteReference	EntityReference	Obligatorio	Salida

Pasos

Nombre	Tipo de paso	Description
Creación de la nota	Crear registro	Title = {NoteTitle(Arguments)} Cuerpo de la nota = {NoteText(Arguments)} Con respecto a = {Contact{Contact}}
Devolver una referencia a la nota	Asignar valor	ValorDeReferenciaNota = {Nota(Crear la nota (Nota))}

Después de publicar y activar la acción personalizada, verá esta nueva acción definida al descargar el CSDL.


<Action Name="new_AddNoteToContact" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.contact" 
    Nullable="false" />
  <Parameter Name="NoteTitle" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <Parameter Name="NoteText" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <ReturnType Type="mscrm.annotation" 
    Nullable="false" />
</Action>

La siguiente solicitud y respuesta HTTP muestran cómo llamar a la acción personalizada y la respuesta que devuelve si se ejecuta correctamente.

Solicitud:

POST [Organization URI]/api/data/v9.2/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

Respuesta:


HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Especificar el parámetro de tipo de tabla

Cuando una acción requiere una entidad como parámetro y el tipo de entidad es ambiguo, use la @odata.type propiedad para especificar el tipo de entidad. El valor de esta propiedad es el nombre completo de la entidad, que sigue este patrón: Microsoft.Dynamics.CRM.+<nombre> lógico de entidad.

Como se muestra en la sección Acciones enlazadas , el Target parámetro de la AddToQueue acción es una actividad. Pero dado que todas las actividades heredan del activitypointer tipo de entidad, debe incluir la siguiente propiedad en el JSON de la entidad para especificar que el tipo de entidad es una letra: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Otros dos ejemplos son las acciones AddMembersTeam y RemoveMembersTeam porque el parámetro Members es una colección de tipo de entidad systemuser, que hereda su clave principal ownerid del tipo de entidad principal. Si pasa el siguiente JSON para representar un único systemuser en la colección, está claro que la entidad es un systemuser y no un tipo de entidad team, que también hereda del tipo de entidad principal.

{
 "Members": [{
  "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
  "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
 }]
}

Si no especifica el tipo de entidad en esta situación, puede obtener el siguiente error: "EdmEntityObject passed should have the key property value set.".

Consulte también

Acciones de API web
Ejemplo de acciones y funciones de API web (C#)
Ejemplo de acciones y funciones de API web (JavaScript del lado cliente)
Realización de operaciones mediante la API web
Redacción de solicitudes HTTP y control de errores
Consultar datos utilizando la API web
Crear una fila de tabla usando la API web
Recuperar una fila de tabla usando la API web
Actualizar y eliminar filas de tablas usando la API web
Asociar y anular la asociación de filas de tabla mediante la API web
Uso de funciones de API web
Ejecución de operaciones por lotes mediante la API web
Suplantar a otro usuario mediante la API web
Realización de operaciones condicionales mediante la API web

Oharrak

Lagungarria al da orri hau?

Last updated on 2026-03-14

Partekatu honen bidez:

Uso de acciones de API web

Acciones sin enlazar

Acciones vinculadas

Acciones enlazadas a una tabla

Acciones enlazadas a una colección de tablas

Utilizar una acción personalizada

Ejemplo de acción personalizada: Agregar una nota a un contacto

Especificar el parámetro de tipo de tabla

Consulte también

Oharrak

Baliabide gehigarriak