We’ve extended Inspire Early Bird Pricing until March 1. Register now and enjoy 20% off conference passes and 10% off training passes. P.S. Don’t forget to bring friends! When you sign up for five or more tickets, you get an extra 20% discount on conference passes.
Learn more now.
URL : The URL for the resource you are trying to access must come from an upstream tool and is the only field required by Alteryx to configure the Download tool. Based on the API you are trying to pull information from (or send data to), other information will be required such as headers and/or a payload.
Output: Configure the output in the way that you wish to receive it to parse downstream. If building a connector, you will most likely keep the default settings,and output to a field as a string. More information about the output and other parameters of the Download tool can be seen on the Alteryx help page.
Tab 2 - Headers
The header of a request is where you place information that must accompany all of your requests. These headers can include things like an authentication token, which indicates your authorization to make the request, as well as the type of the content that you are sending with the request. The documentation for the API you are working with should contain information on the exact headers that you are required to use in order to utilize the service.
Adding a header in the Download tool can be done 2 ways, and you can use a combination of both methods in the same tool.
1. From a constant value: If you know that you will be using a consistent header that will only be utilized in the current Download tool you are working in, the constant value is the way to go. This step requires that you add the key value pair directly to the Headers section. In the example below the tool will send the Header “content-type” with the value “application/json”.
2.From a field: If you need to process your header prior to sending it, such as base 64 encoding it, or if the header relies on previous calls to the API such as a call to an authorization endpoint, use this option. Make sure that the name of the field is the name of the header you wish to send, which is the name the Download tool will utilize to send the header. In the example below, the tool will use “Authorization” as the header name, and the value of the field as the value to send.
Tab 3 - Payload
HTTP Action: The API that you are working with should dictate which HTTP action to use for certain endpoints. These will most often be GET to retrieve data, and POST to send or upload data, but always refer to the documentation to be sure.
Query String/Body: There are many different ways of implementing a payload/query/body with the Download tool. The payload/query is the data that is normally listed after the question mark in a URL example. Below are examples of different ways to implement this example request from the Quandl API site.
1.Appended directly to the URL: You can take this string directly as it is and use it as the value of the URL in the Download tool. This is fine for a one time use, but in building a reusable connector, you would likely want to build the query using one of the other options so that some of the data could be parameterized. This option would require no selection on the Payload tab of the Download tool other than the HTTP Action.
2.Compose Query String/Body:
From constant values : In this option you write out the key value pairs for the parameter and value.
From field values: This option takes the name of the field as the name, and the value of the field as the value for the parameter that you are sending.
You can also use a combination of both constant and from field values:
3.Take Query String/Body from Field: Add the entire body of the query to a field and use the value of that field here. This can be a good option if your entire payload of the request has to be formatted as a JSON object.
4.Use Following for Query String/Body: You can directly add the query string to the Download tool:
Tab 4 - Connection
Username & Password: These fields are most commonly used if utilizing the Download tool for FTP/SFTP.
Maximum Connections: This field defaults to 2 and has a maximum value of 32. Exercise caution when increasing this number, as to not overload the server you are accessing or exceed rate limitations of the web service.
Timeout: If you are having issues with the request timing out with the service you are accessing (this will be seen by an error message that indicates a timeout), increase this number so that you allow the service more time to respond to your request.
Multiple Download Tool Requests: When working with the Download tool, a request will be executed for every row of data that is passed in. This makes it is a very useful practice to have all of your Download tool configurations contained in fields, so that you may use the headers and query string/body options that take the data from fields. By parameterizing this data, you can add one Download tool to your canvas and execute multiple requests. If you are attempting to create a reusable connector however, you may instead create a supporting sub-macro that executes a request and parses the data, so that the response data from multiple requests can be joined together. You should evaluate what works best for your situation based on what the desired outcome is. The example below contains the request data to retrieve 2 different data sets from the Quandl API. If fed into a Download tool, it will execute one request for each row of information.
Rate Limitations: The service that you are working with may have limitations on the number of total requests you can execute per day, per second, per minute, etc. If you are executing multiple requests through one Download tool you will want to pay attention to these limitations. The Throttle tool is a very useful mechanism for handling these rate limitations. For example, if the API you are working with limits you to 1 request per second, you could add the Throttle tool prior to the Download tool, and use its default value of 60 to achieve the rate limitation. If you were limited to 2 per second, you could change the Throttle tool's value to 120.
Paging for Results: If you are working with a service that had the possibility of returning a relatively large set of data, the service may have a process to indicate that there are more records than what is currently being returned. This usually takes the form of something like a next page token, or a flag that indicates that there are still more records, and you may need to increment your current “page” or parse out the next page token to send back for the rest of the data. This type of behavior can be achieved by using an iterative macro. The example below shows a sample set of tools that would be contained in an iterative macro that your connector could utilize.
The top row shows the request being made, and the JSON being parsed and output.
The bottom row shows that if a certain condition is met, such as if a next page token is present, you can do the processing that is needed, generate the new URL to include the next page token, and the macro will execute again based on this new request URL.
To configure the iterative macro settings, you use the Interface Designer window. This allows you to specify the Iteration Input tool, the Iteration Output tool, and the method to union the results. To read more about iterative macros check out the help page.