Usar acciones de la API web

  • Artículo

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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 y estarán disponibles para uso.

En este tema

Acciones sin enlazar

Acciones enlazadas

Utilizar una acción personalizada

Especificar tipo de parámetro de la entidad

Acciones sin enlazar

Las acciones se definen en d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Por ejemplo, la siguiente es la definición de la WinOpportunity Action representada en CSDL.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

La acción WinOpportunity corresponde a WinOpportunityRequest utilizando el servicio de organización. Use esta acción para establecer el estado de una oportunidad como Ganada y crear un opportunityclose EntityType para registrar el evento. Esta acción no incluye un valor de devolución. Si tiene éxito, la operación está completa.

El parámetro OpportunityClose requiere una representación de JSON de la entidad opportunityclose para crear en la operación. Esta entidad debe estar relacionada con la oportunidad que se deriva de la propiedad de navegación de un solo valor opportunityid. En JSON esto se establece mediante la anotación @odata.bind, como se explica en Asociar entidades en la creación.

El parámetro Status debe establecerse en el estado de la opportunity en el momento en que se cerró. Puede encontrar el valor predeterminado para esto en la propiedad opportunity EntityType statuscode. La opción Ganado tiene un valor de 3. Puede preguntarse por qué es necesario configurar este valor si solo hay una opción de razón para el estado que representa Ganado. La razón es que puede definir opciones de estado personalizadas para representar un logro, como Gran logro o Pequeño logro,por lo que el valor potencialmente podría ser distinto de 3 en esa situación.

El siguiente ejemplo es la solicitud y la respuesta HTTP para llamar a la acción WinOpportunity para una oportunidad con un valor opportunityid de b3828ac8-917a-e511-80d2-00155d2a68d2.

  • Solicitud

    POST cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Status": 3,
 "OpportunityClose": {
  "subject": "Won Opportunity",
  "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

  • Respuesta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Acciones enlazadas

En d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, cuando un elemento Action representa una acción enlazada, tiene un atributo IsBound con el valor true. El primer elemento Parámetro 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. Por ejemplo, lo siguiente es la definición de la AddToQueue Action representada en 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 es equivalente a la AddToQueueRequest usada por el servicio de organización. En API web esta acción está enlazada a queue EntityType que representa la propiedad AddToQueueRequest.DestinationQueueId. Esta acción acepta varios parámetros adicionales y devuelve un AddToQueueResponse ComplexType correspondiente a la AddToQueueResponse devuelta por el servicio de organización. 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 enlazada debe llamarse mediante un URI para establecer el primer valor de parámetro. No puede establecerlo como un valor de parámetro con nombre.

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.

El siguiente ejemplo muestra el uso de la AddToQueue Action 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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Utilizar una acción personalizada

Si define acciones personalizadas para su organización o solución, estas también se incluirán en d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Para obtener información sobre cómo crear acciones mediante las herramientas de personalización en la aplicación, vea el TechNet tema Acciones. Para obtener información sobre cómo crear y usar sus propias acciones personalizadas, consulte Crear acciones propias.

Independientemente de si las operaciones incluidas en la acción personalizada tienen efectos secundarios, potencialmente pueden modificar datos y, por tanto, se consideran acciones en lugar de funciones. No hay forma de crear una función 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)}

Regarding = {Contact{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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Especificar tipo de parámetro de la entidad

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 arriba, el parámetro Target con la AddToQueue Action es una actividad. Pero dado que todas las actividades se heredan del activitypointer EntityType, debe incluir la propiedad siguiente en la entidad JSON para especificar que el tipo de entidad es una carta: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Otros dos ejemplos son AddMembersTeam Action y RemoveMembersTeam Action porque el parámetro Members es una colección de systemuser EntityType que hereda su clave principal ownerid del principal EntityType. Si pasa el JSON siguiente para representar un solo systemuser en la colección, está claro que la entidad es un systemuser y no un team EntityType, que también se hereda del entitytype 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.".

Ver también

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 utilizando la API web
Cree una entidad usando API web
Recuperar una entidad usando API web
Actualizar y eliminar entidades mediante la API web
Asociar y anular la asociación de entidades 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

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright