Pular para o conteúdo principal

FV Decipher Support

Todos os tópicos, recursos necessários para FV Decipher.

Base de Conhecimento da FocusVision

Generic API Call

Overview

You can use the Logic Library to suspend a survey and execute an API call via HTTP/HTTPS to a remote server. This is done using the API logic node.

1: Logic Syntax

There are two steps you will need to follow when formatting any API call:

  1. Create a variable that will define the call parameters. Call parameters include what gets passed in the URL (in the GET request).
  2. Write the following exec code, specifying alabel for your API call, along with your preset variable name (api:params) and its URL (api:url):
    <exec>
     <logic uses="api.1" label="xxxx" api:params="yyyy"
       api:url="http://api.exampledomain.com"
      />
    </exec>

2: Parameters

The following parameters can be passed using the API logic node:

Attribute Description
api:url This attribute is required and is the base URL to access. The hostname must exist in the api.txt file located in the company directory (selfserve/XXX) or be white-listed within the api.1 logic node.
api:params This attribute is optional. It is the name of a variable that contains the URL parameters and must be a dictionary. For example, if you specify api:params="weather_data" and you've run the code weather_data = {"q": "Copenhagen", "when" : "yesterday"}, then the API call will have ?q=Copenhagen&when=yesterday added to it, along with any special characters.
api:data This attribute is the same as api:param , but uses large data sent in the body of a HTTP POST request.
api:method This attribute specifies the call method. It can be set to GET (default), POST, DELETE, or PUT.

The API call is not able to pass custom headers. The default header passed when utilizing the PUT method is "application/x-www-form-urlencoded".

The Logic Library is continually growing and new logic nodes are being added all the time. If you are looking for more functionality with your call, contact your support team to inquire about development of new custom logic nodes for specific API calls.

Once you execute the code above, your survey will be suspended and you can check your variable name on the next page for the HTTP status code.

3: Interpreting Call Results

To determine whether your API call was successful, you will want to check your node:status and node.r values. The node:status value will be your HTTP status code. If your API call is successful, you should see a status code of "200" here. If the server responds with any other code, there are likely errors in your call; for example, an invalid URL will result in a  "500" status code.

If you receive an error code, you will want to check both your logic syntax and the results of the call.

If you are running SST, node.status will return 500.

The node.r value will be the response value of your call. If the API call returned JSON data, this is automatically decoded. Otherwise, you should see raw text here. If your call was successful, you will not need to do anything; the request and response will be logged automatically.

Example

If you wanted to open a page in your survey that showed the weather in respondents' current locations, you might use the following code (where the api:url is Open Weather's weather map webpage and q is the respondent's response to "q" - a survey question asking them "In what city do you currently reside?"):

<exec>
weather_data = dict(q=city.val)
</exec>
<logic uses="api.1" label="weather" api:params="weather_data"
     api:url="http://api.openweathermap.org/data/2.5/weather"
      />
<exec>
if weather.status == 200 and weather.r["cod"] == 200:
  p.temperature = str(weather.r["main"]["temp"] - 273.15)
else:
  p.temperature = None
</exec>

Each API may have a different way of returning errors, and OpenWeather will have a "cod" field in place of the "node:status" value with either "200" or another status code. Similarly, instead of "node:r", this call will show The weather.r as will be the result.

OpenWeather also returns the temperature in Kelvin, rather than Fahrenheit or Celsius.

  • Este artigo foi útil?