| --- |
| title: POST /geode/v1/functions/{functionId} |
| --- |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| Execute <%=vars.product_name%> function on an entire cluster or on a specified region, members, and member groups. |
| |
| ## Resource URL |
| |
| ``` pre |
| /geode/v1/functions/{functionId}?[&onRegion=regionname|&onMembers=member1,member2,...,memberN|&onGroups=group1,group2,...,groupN] |
| ``` |
| |
| ## Parameters |
| |
| - **{functionId}** This required parameter is the name of the function to execute. Place it in the resource URL, as in the example request: `AddFreeItemToOrders`. |
| - **onRegion** This optional parameter specifies the target region for the function. You can only invoke a function on a single region. Substitute the region's name for `regionname` within the sample syntax `onRegion=regionname`. |
| - **onMembers** This optional parameter specifies the target members of the function. For multiple members, specify a comma-delimited list of member names, as in the sample `onMembers=member1,member2`. |
| - **onGroups** This optional parameter specifies the target groups of the function. For multiple groups, specify a comma-delimited list of group names, as in the sample `onGroups=membergroup1,membergroup2`. |
| - **filter** This optional parameter can only be used with the **onRegion** parameter, where the region has a `data-policy` of `PARTITION`. The parameter specifies a list of applicable keys that the function needs to filter on. There are three keys in the example resource URL: |
| |
| ``` pre |
| http://serverURL/functions/SampleFunction?onRegion=TestPartitionRegion&filter=key1,key2,key3 |
| ``` |
| - Any *function arguments* are passed in the request body in JSON format. The content of the arguments depends on how the function is defined. Each function argument must be written as a JSON object (enclosed in braces `{ }`) and using `@type` to declare its type. `@value` can be used to specify a scalar value. Nested JSON objects (`{ }`) or JSON collections (`[ ]`) are not accepted. |
| Collections of Java objects cannot be specified as parameters in JSON format, so if a function expects a collection of objects as one of its arguments (for example, `function(List<Item> list)`), it cannot be called using the <%=vars.product_name%> REST API. Following are some examples of functions and their arguments in JSON format: |
| |
| <table> |
| <colgroup> |
| <col width="50%" /> |
| <col width="50%" /> |
| <col width="50%" /> |
| </colgroup> |
| <thead> |
| <tr class="header"> |
| <th>Function signature</th> |
| <th>Function arguments in JSON format</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td> |
| <pre>myFunction1(int n)</pre> |
| </td> |
| <td> |
| <pre> |
| [ |
| { |
| "@type": "integer", |
| "@value": 10 |
| } |
| ] |
| </pre> |
| </td></tr> |
| <tr> |
| <td> |
| <pre>myFunction2(double d, Item i)</pre> |
| </td> |
| <td> |
| <pre> |
| [ |
| { |
| "@type": "double", |
| "@value": 210 |
| }, |
| { |
| "@type": "org.apache.geode.web.rest.domain.Item", |
| "itemNo": "599", |
| "description": "Part X Free on Bumper Offer", |
| "quantity": "2", |
| "unitprice": "5", |
| "totalprice": "10.00" |
| } |
| ] |
| </pre> |
| Notice how `item` fields are written in JSON format due to the restrictions against nested objects. The following approach would be wrong: |
| <pre> |
| [ |
| { |
| "@type": "double", |
| "@value": 210 |
| }, |
| { |
| "@type": "org.apache.geode.web.rest.domain.Item", |
| "itemNo" : { |
| "@type":"double", |
| "@value": 599 |
| }, |
| "description": "Part X Free on Bumper Offer", |
| "quantity": "2", |
| "unitprice": "5", |
| "totalprice": "10.00" |
| } |
| ] |
| </pre> |
| </td></tr></table> |
| |
| |
| |
| |
| ## Example Requests |
| |
| ``` pre |
| Request Payload: application/json |
| POST /geode/v1/functions/AddFreeItemToOrders |
| Accept: application/json |
| Content-Type: application/json |
| |
| [ |
| { |
| "@type": "double", |
| "@value": 210 |
| }, |
| { |
| "@type": "org.apache.geode.web.rest.domain.Item", |
| "itemNo": "599", |
| "description": "Part X Free on Bumper Offer", |
| "quantity": "2", |
| "unitprice": "5", |
| "totalprice": "10.00" |
| } |
| ] |
| ``` |
| |
| Another example: |
| |
| ``` pre |
| Request Payload: null |
| |
| POST /geode/v1/functions/getDeliveredOrders |
| Accept: application/json |
| ``` |
| |
| ## Example Success Responses |
| |
| ``` pre |
| Response Payload: null |
| 200 OK |
| Location:http: //localhost:8080/geode/v1/functions/AddFreeItemToOrders |
| ``` |
| |
| Another example response: |
| |
| ``` pre |
| Response Payload: application/json |
| |
| 200 OK |
| Content-Length: 316 |
| Content-Type: application/json |
| Location: http://localhost:8080/geode/v1/functions/getDeliveredOrders |
| [ |
| { |
| "purchaseOrderNo": "1121", |
| "deliveryDate": "Thu Oct 10 00:00:00 IST 2019" |
| }, |
| { |
| "purchaseOrderNo": "777", |
| "deliveryDate": "Thu Oct 10 00:00:00 IST 2019" |
| }, |
| { |
| ... |
| } |
| ] |
| ``` |
| |
| ## Error Codes |
| |
| Status code 500 INTERNAL SERVER ERROR is an error encountered in a server. Check the HTTP response body for a stack trace of the exception. |
| |
| |