Share via

2.2.3.6.5 Action Parameters

  • Article

Applies to the OData 3.0 protocol

Actions are represented by using FunctionImport elements, as specified in [MC-CSDL] (section 2.1.15).

Actions are invoked by using a POST request to a URI that identifies an action. Where specified, parameters to actions MUST be provided in the POST body. If not specified, parameter values MUST be assumed to be null.

The POST body MUST be encoded in JSON format (according to Action Parameters in [ODataJSON4.0] section 17) or in Verbose JSON format 2.2.6.3. Therefore, the Content-Type of the POST request SHOULD be set to application/json or application/json;odata=verbose, respectively.

When passing parameters by using the Verbose JSON format, the body MUST consist of a single JSON object. Each parameter that is specified in the body MUST be a top level property of this single JSON object, where the property name is the same as the parameter name and the property value is the standard OData Verbose JSON encoding for that parameter type (Verbose JSON Format (section 2.2.6.3)).

Any parameters to the action that is identified by the request URI that are omitted MUST be interpreted as having a null value.

A client MAY choose to provide no Body and Content-Type header if the Action has either no parameters or all parameter values are null.

To pass parameters to an action in a POST request body by using the preferred OData 3.0 JSON format, see Action Parameters in [ODataJSON4.0] section 17. To pass parameters by using the Verbose JSON format, the following syntax is used.

 ; OData 3.0 only
 actionParametersInVJson = begin-object
                     [actionParameter]
                     *(value-seperator actionParameter)
                     end-object
  
 actionParameter = quotation-mark 
                   actionParameterName 
                   quotation-mark 
                   name-seperator 
                   actionParameterValue
  
 actionParameterName = *pchar   ; section 3.3 of [RFC3986]
      ; the name of a parameter to an Action defined as a
      ; FunctionImport in the EDM 
      ; model associated with the data service
  
 actionParameterValue = nullLiteral | 
                        primitiveValueInVJson |
                        entityTypeBody |
                        entityCTBody |
                        collectionInVJson |
                        entityCollectionValueInVJson
                                                   
  
 primitiveValueInVJson = <EDMSimple type serialized as per section 2.2.6.3.1>
  
  
 entityTypeBody   =  ; section 2.2.6.3.3
 entityCTBody     =  ; section 2.2.6.3.4
 collectionInVJson = ; section 2.2.6.3.3
 entityCollectionValueInVJson = ; section 2.2.6.3.2
 nullLiteral      =  ; section 2.2.3.6.1.1
 begin-object     =  ; [RFC4627] section 2
 name-seperator   =  ; [RFC4627] section 2
 value-seperator  =  ; [RFC4627] section 2

Listing: ABNF Grammar for Action Parameters