Invoke URL

invokeURL task for API calls

Overview

The invokeUrl task is an HTTP client that allows you to access and modify:

  • web resources using HTTP calls.
  • data of one Zoho service from another Zoho service using the URL specified in its API
  • data of a third-party service connected to your Zoho service using the URL specified in its API. Click here to learn how you can connect your Zoho service with a third-party service using connections.
Note:
  • This task will throw "socket timeout error" if the web resource/ API takes more than 40 seconds to respond. 
  • Using this task, you can download files of size up to 50 MB in Zoho Creator and 5 MB in other services.

Syntax

response = invokeUrl
[ 
 url: <url_value> 
 type: [<type_value>] 
 headers: [<headers_value>] 
 content-type: [<content_type_value>] 
 parameters: [<parameters_value>] 
 files: [<files_value>] 
 connection: [<connection_name>] 
 detailed: [<detailed_value>] 
 response-format: [<response_format_value>] 
 response-decoding: [<encoding_format_value>] 
];
ParameterData typeDescription

<response>

KEY-VALUE/ FILE/ TEXT/ LIST

The variable that will contain the response returned.

<url_value>

 

TEXT

The request URL whose resources need to be accessed.

<type_value>

(optional)

Constant

The HTTP request method.

Allowed values:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Default value: GET

<headers_value>

(optional)

KEY-VALUE

The attributes or the header values.

<content_type_value>

(optional)*

KEY-VALUE

The type of content that needs to be sent in the body of the HTTP request.

Allowed values: Any valid content type. Eg, multipart/form-data, application/x-www-form-urlencoded, application/json, etc.

Default value:

  • application/x-www-form-urlencoded, if the body is KEY-VALUE.
  • text/plain, if the body is TEXT.
*Note: This parameter is not applicable to Zoho Creator.

<parameters_value>

(optional)

TEXT/FILE/ KEY-VALUE

The body of the request.

Send various types of request body using invokeUrl:

  • Raw:
    TEXT data to this parameter will be sent as raw type.
     
  • x-www-form-urlencoded:
    KEY-VALUE data to this parameter will be sent as x-www-form-urlencoded type.
     
  • Form-data:
    KEY-VALUE data to this parameter will be sent as multipart form-data type, if the value of the content-type parameter is specified as multipart/form-data.

    Note:
    • If the value of the content-type parameter is not specified as multipart/form-data, the KEY-VALUE data is treated as x-www-form-urlencoded type.
    • In Zoho Creator, the multipart/form-data values must be specified in files parameter
       
  • Binary:
    FILE data is sent as binary type.

    Note:
    • The value of the <content-type> parameter must be specified as application/octet-stream, to recognize that the body is sent as binary type.
    • Binary type is not applicable to Zoho Creator.

<files_value>

(optional)

FILE/ TEXT/ KEY-VALUE/ LIST of FILE/ LIST of TEXT/ LIST of KEY-VALUE

In Zoho Creator, if the body of the request needs to be sent as multipart form-data, the values need to be are supplied to this parameter.

Note:

  • Only the files received as the response of an invokeUrl task can be attached.
  • This parameter can also be used in services other than Zoho Creator. However, to send multipart form-data from services other than Zoho Creator, we recommend that you supply the values as KEY-VALUE to the body parameter while specifying the content-type parameter as multipart/form-data.
  • The toFile function can be used here. For example, you can take a text value in csv format and use the 'toFile' function to pass it as a csv file. Please note that this function is currently not applicable to Zoho Creator.
Format to send KEY-VALUE data,
  • If the value associated with the key is FILE:
<variable> = {"paramName": <key>, "content": <File>};
  • If the value associated with the key is TEXT:
<variable> = {"paramName": <key>, "content": <Text>, "stringPart": "true"};
Format to send LIST of FILE data:
<File1>.setParamName(<FileName1>);
<File2>.setParamName(<FileName2>);
list_of_files = List();
List.add(<File1>);
List.add(<File2>);
setParamName built-in function is used to set the specified name for the file object that needs to be sent in multipart form-data using invokeUrl. This function cannot be applied on files fetched using fetch records task or input.<field_name> expression.

Format to send LIST of TEXT data:

list_of_text = List();
List.add(<Text1>);
List.add(<Text2>);
Format to send LIST of KEY-VALUE data,
  • If the values to the keys are FILES:
list_of_key_value = List();
list_of_key_value.add({"paramName": <key1>, "content": <File1>});
list_of_key_value.add({"paramName": <key2>, "content": <File2>});
  • If the values to the keys are of TEXT data type:
list_of_text = List();
list_of_text.add({"paramName": <key1>, "content": <Text1>, "stringPart": "true"});
list_of_text.add({"paramName": <key2>, "content": <Text2>, "stringPart": "true"});

<connection_name>

(optional)

TEXT

The connection name of the required service.

Note: Multiple connections can be created for the same service.

<detailed_value>

(optional)

BOOLEAN

This parameter decides if a detailed response needs to be returned.

Allowed values: 

  • true - returns response code (HTTP status code), header response, and response content as KEY-VALUE.
  • false - returns the response content.

Default value: false

<response_format_value>

(optional)*

Constant

If this parameter is supplied with the value - FILE, the response is converted and returned as a FILE object.

Allowed values: FILE

*Note: This parameter is not applicable to Zoho Creator.

<encoding_format_value>

(optional)

TEXT

The character encoding scheme with which the response returned needs to be decoded.

Allowed values: Click here to find the list of allowed values to this parameter.

Default value: UTF-8

Example 1: Fetch a file from the web

The following script fetches an image from the web using its URL:

 response = invokeUrl
 [
 url: "http://www.thenonlinearpath.com/wp-content/uploads/2016/05/GoodVibesOnly.png"
 type: GET
 ];

where:

response
TheFILE that holds the image that will be fetched from the web.
"http://www.thenonlinearpath.com/wp-content/uploads/2016/05/GoodVibesOnly.png"
The TEXT that represents the URL of the image that needs to be fetched.
GET
The HTTP request method.

Example 2: Create a contact in Zoho Books using invoke URL

The following script creates a contact with the specified values in Zoho Books using the URL specified in the Zoho Books API:

 // Create a map that holds the values of the new contact that needs to be created
 contact_info = Map();
 contact_info.put("contact_name", "Shawn");
 // Format the data as specified in the Zoho Books API
 data  = Map();
 data.put("JSONString", contact_info);
 // Supply the URL and parameters to the invoke URL task
 response = invokeUrl
 [
 url: "https://books.zoho.com/api/v3/contacts?organization_id=58XXXX07"
 type: POST
 parameters: data
 connection: "books_api_connection"
 ];

where:

"https://books.zoho.com/api/v3/contacts?organization_id=58XXXX07"
The TEXT that represents the URL specified in the Zoho Books API to create a contact.
POST
The HTTP request method.
data
The KEY-VALUE variable that holds the values of the contact that needs to be created.
"books_api_connection"
The TEXT that represents the connection name.

Example 3: Tweet using Deluge from the connected Twitter account

The following script posts a tweet message - Good Morning from the connected twitter account. The tweet message is supplied as a URL parameter concatenated to the URL specified in the twitter API.

 // Create a variable to hold the tweet message
 query_param = "Good Morning";
 // Supply the URL and parameters to the invoke URL task
 response = invokeUrl
 [
 url: "https://api.twitter.com/1.1/statuses/update.json?status=" + query_param
 type: POST
 connection: "twitterConnection"
 ];

where:

"https://api.twitter.com/1.1/statuses/update.json?status="
The TEXT that represents the URL to tweet which is specified in the Twitter API.
query_param
The TEXT variable that holds the tweet message which will be sent as a query parameter.
"twitterConnection"
The TEXT that represents the name of the connection.

Example 4: Fetch the list of files from the connected Dropbox account

The following script fetches all the files from the folder - test_folder of the connected Dropbox account using its API:

 // Create a variable to hold the parameters that is required by Dropbox API
 raw_data = Map();
 raw_data.put("path", "/test_folder");
 // Create a variable to hold the headers that is required by Dropbox API
 header_data  = Map();
 header_data.put("Content-Type", "application/json");
 // Supply the URL, parameters, and headers to the invoke URL task
 response = invokeUrl
 [
 url: "https://api.dropboxapi.com/2/files/list_folder"
 type: POST
 parameters: raw_data.toText()
 headers: header_data
 connection: "dropbox_connection"
 ];

where:

"https://api.dropboxapi.com/2/files/list_folder"
The TEXT that represents the URL specified in the Dropbox API to fetch all the files from the specified folder.
raw_data.toText()
The TEXT that holds the path of the folder. The toText is a Deluge built-in function that converts a value into TEXT data type. Click here to learn more about it.
header_data
The KEY-VALUE variable that holds the header values required by Dropbox API.
"dropbox_connection"
The TEXT that represents the name of the connection.
Note: Click here to find the list of ports in which the invoke URL task can be executed.

Response Format

Success Response
  • The success response when the <need_detailed_response> param is set to true, will be returned in the following format:
        {
      "responseText": "GoodVibesOnly.png",
      "responseHeader": {
        "date": "Wed, 23 Oct 2019 10:03:31 GMT",
        "server": "Apache",
        "content-length": "159500",
        "expires": "Wed, 23 Oct 2019 16:03:31 GMT",
        "x-endurance-cache-level": "2",
        "x-cache-lookup": "MISS from 172.30.232.40:3128",
        "via": "1.1 172.30.232.40 (squid/4.1)",
        "last-modified": "Wed, 04 May 2016 01:44:18 GMT",
        "content-type": "image/png",
        "connection": "keep-alive",
        "x-cache": "MISS from 172.30.232.40",
        "accept-ranges": "bytes",
        "cache-control": "max-age=21600"
        },
        "responseCode": 200
        }

To fetch the content-type from the response header obtained, execute the following script:

 <variable>=response.get("responseHeader").get("content-type");

Related Links

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohodeluge.com