Uso de acciones de API web

Las acciones y funciones representan operaciones reutilizables que puede realizar mediante la API web. Use una POST solicitud con acciones enumeradas en Web API Action Reference para realizar operaciones que tengan efectos secundarios. También puede definir acciones personalizadas. Más información: Cree 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 es 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 acción Merge corresponde a MergeRequest utilizando 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 realizar 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: Combinar filas de tabla mediante la API web

Acciones vinculadas

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

En el documento $metadata CSDL, cuando un Action elemento representa una acción enlazada, tiene un IsBound atributo con el valor 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, debe incluir 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

Como ejemplo de una acción enlazada a una entidad, la siguiente es la definición de la AddToQueue acción 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 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.

Se 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 el uso de la AddToQueue acción para agregar una letra a una cola. Dado que el 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 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. Estos son algunos de los 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 es la definición de 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, el enlace de colección de entidades simplemente aplica la restricción que el URI de la solicitud debe incluir la ruta de acceso al conjunto de entidades especificado.

En el ejemplo siguiente se muestra el uso de la ExportTranslation acción , que exporta un archivo binario que contiene datos sobre valores de cadena localizables que se pueden actualizar para modificar o agregar valores localizables. Observe cómo la acción enlazada a la colección de entidades es 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 personalizado. 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 ejemplo siguiente es para 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, al descargar el CSDL encontrará esta nueva acción definida.


<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 muestra 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, debe usar 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 anterior, 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 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

Comentarios

Resultoulle útil esta páxina?

Last updated on 2025-10-22

Compartir por

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

Comentarios

Recursos adicionais