Usar acciones de la API web

Artículo
09/29/2023

Las acciones y funciones representan operaciones reutilizables que puede realizar mediante la API web. Use una solicitud POST con las acciones que aparecen en Web API Action Reference para realizar operaciones que tienen efectos secundarios. También puede definir acciones personalizadas. Más información: Crear sus propios mensajes.

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

Acciones sin enlazar

El XML siguiente es la definición de la acción Merge 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 acción Merge corresponde a MergeRequest utilizando el SDK para .NET. Utilice esta acción para fusionar un par de registros duplicados. Esta acción no incluye un valor de devolución. Si se realiza correctamente, la operación se habrá completado.

El siguiente ejemplo es la solicitud HTTP y la respuesta para llamar a la acción Merge para 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

Más información: Fusionar filas de tabla usando la API web.

Acciones enlazadas

Hay dos formas de vincular una acción. La forma más común es que la acción esté vinculada por una entidad. Con menos frecuencia, también se puede vincular a una colección de entidades.

En el Documento de $metadatos CSDL, cuando un elemento Action representa una acción enlazada, tiene un atributo IsBound con el valor true. El primer elemento Parameter definido en la acción representa la entidad a la que está enlazada la operación. Cuando el atributo Type del parámetro es una colección, la operación está enlazada a una colección de entidades.

Cuando invoca una función enlazada, debe incluir el nombre completo de la función incluido el espacio de nombres Microsoft.Dynamics.CRM. Si no incluye el nombre completo, recibirá el siguiente error: Status Code:400 Request message has unresolved parameters.

Acciones vinculadas a una tabla

Como ejemplo de una acción ligada a una entidad, a continuación se define la acción AddToQueue representada en el CSDL:

 <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 vinculada a la entidad es equivalente a la AddToQueueRequest utilizada por SDK para .NET. En la API web, esta acción está vinculada al tipo de entidad queue que representa la propiedad AddToQueueRequest .DestinationQueueId . Esta acción acepta varios parámetros adicionales y devuelve un tipo complejo AddToQueueResponse que se corresponde a la AddToQueueResponse que devuelve SDK para .NET. Cuando una acción devuelve un tipo complejo, la definición del tipo complejo aparecerá directamente sobre la acción en el CSDL.

Una acción vinculada a una entidad debe invocarse mediante un URI para establecer el primer valor de parámetro. No puede establecerlo como un valor de parámetro con nombre.

El siguiente ejemplo muestra el uso de la acción AddToQueue para agregar una carta a una cola. Dado que el tipo de tipo de parámetro Target no es específico (mscrm.crmbaseentity), debe declarar explícitamente el tipo de objeto usando el valor de propiedad @odata.type del nombre completo de la entidad, incluido el espacio de nombres de Microsoft.Dynamics.CRM. En este caso, Microsoft.Dynamics.CRM.letter. Más información:Especificar tipo de parámetro de la 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 vinculadas a una colección de tabla

Es menos común encontrar acciones vinculadas a una colección de entidades. Los siguientes son algunos que puede encontrar:

FulfillSalesOrder en Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Como ejemplo de una acción ligada a una colección de entidades, a continuación se define la acción ExportTranslation representada en $metadata de 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 vinculada a la colección de entidades es equivalente a la ExportTranslationRequest utilizada por el SDK para .NET. En la API web, esta acción está vinculada al tipo de entidad solution. Pero en lugar de pasar un valor a la solicitud, el enlace de la colección de entidades simplemente aplica la restricción de que el URI de la solicitud debe incluir la ruta al conjunto de entidades especificado.

El siguiente ejemplo muestra el uso de la acción ExportTranslation que exporta un archivo binario que contiene datos sobre valores de cadena localizables que se pueden actualizar para modificar o agregar valores localizables. Tenga en cuenta cómo la acción vinculada a la colección de entidades tras el nombre del conjunto de entidades para la entidad de la 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. De cualquier forma que se cree, habrá una operación correspondiente que puede utilizar. Con la API personalizada, la operación puede ser una función. Más información: Crear sus propios mensajes

El siguiente ejemplo es para una acción de proceso personalizada.

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

Digamos 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 de contacto con las siguientes propiedades.

UI Label	valor
Nombre del proceso	AddNoteToContact
Nombre único	new_AddNoteToContact
Entidad	Contacto
Categoría	Acción

Argumentos de procesos

Nombre	Tipo	Requerido	Dirección
NoteTitle	Cadena	Requerido	Entrada
NoteText	Cadena	Requerido	Entrada
NoteReference	EntityReference	Requerido	Salida

Pasos

Nombre	Tipo de paso	Descripción
Crear la nota	Crear registro	Title = {NoteTitle(Arguments)} Note Body = {NoteText(Arguments)} referente = {Contacto{Contact}}
Devuelve una referencia a la nota	Asignar valor	NoteReference Value = {Note(Create the note (Note))}

Tras publicar y activar la acción personalizada, cuando descargue el CSDL encontrará esta nueva acción especificada.


<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 solicitud y respuesta HTTP siguientes muestran cómo llamar a la acción personalizada y la respuesta que devuelve si es correcta.

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

Permite 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, debe usar la propiedad @odata.type 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.+<entity logical name>.

Como se muestra en la sección Acciones enlazadas anterior, el parámetro Target para la acción AddToQueue es una actividad. Pero como todas las actividades heredan del tipo de entidad activitypointer, 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 tipos de entidad systemuser, que hereda su clave primaria 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 la API web
Ejemplo de funciones y acciones de la API web (C#)
Ejemplo de funciones y acciones de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos mediante 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
Usar funciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web

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

Usar acciones de la API web

Acciones sin enlazar

Acciones enlazadas

Acciones vinculadas a una tabla

Acciones vinculadas a una colección de tabla

Utilizar una acción personalizada

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

Permite especificar el parámetro de tipo de tabla

Consulte también

Recursos adicionales