Rest and Json
The Syncer allows you to directly import Json Files or Simple Rest APIs, which return plain Json and don't have special Authentication.
Rest API
Everything is configured using an Account. The Following Options are available:
| Option | Description |
|---|---|
auth_type |
Empty if you want a Header based auth, else Basic or Digest |
cert |
Path to a Certificate for Certificat Based auth |
request_headers |
Send Custom Headers like for Auth or Content Type |
data_key |
Empty or key where the Data will be found. |
hostname_field |
In which field can the Hostname be found |
rewrite_hostname |
Jinja if you want to rewrite the hostname |
method |
The request can be changed from GET to POST. |
post_body |
If POST mode, specify the JSON Body here, Jinja is supported |
page_limit |
Records per request, reads the API page by page. Empty reads everything at once |
page_offset_field |
Name of the API parameter for the records to skip, default offset |
page_limit_field |
Name of the API parameter for the records per page, default limit |
filter_field |
Field of a record that is checked against filter_lookup_table |
filter_lookup_table |
Lookup Table whose first column lists the values to import |
POST Body with Jinja
Since 4.5
post_body is rendered with Jinja before the request is sent. All
Jinja functions work there, including
{{ACCOUNT:name:field}}, secret_value() and the
Lookup Tables. There are no host attributes,
the body is built once per import.
To send one entry per line of a lookup table, loop over lookup_rows().
Use the tojson filter for the values, it adds the quotes and escapes
whatever would break the JSON:
{"filter": [{% for row in lookup_rows('sites') %}{"name": {{ row.location | tojson }}, "dc": {{ row.datacenter | tojson }}}{% if not loop.last %},{% endif %}{% endfor %}]}
If the columns of the table already match the fields the API expects, the whole table can be sent as a list:
{"items": {{ lookup_rows('sites') | tojson }}}
An undefined variable or a syntax error stops the import with an error instead of sending a broken body.
Paging
Since 4.5
An API that returns too many records for one answer can be read page by
page. Set page_limit to the number of records per request, it is sent
as the value of page_limit_field. The Syncer then asks with an offset
of 0, then with page_limit, then with twice page_limit and so on,
until a page brings fewer records than page_limit.
page_offset_field and page_limit_field name the parameters the API
expects for the records to skip and the records per page. With GET
they are sent as URL parameters, with POST they are added to the top
level of post_body, which then has to be a JSON object. For
page_limit 500 and the default field names, the second request of a
POST sends:
{"conditions": [], "offset": 500, "limit": 500}
If the API ignores these parameters and keeps sending the same records, the import stops with an error instead of asking forever.
Filter with a Lookup Table
Since 4.5
Some APIs can't filter for a long list of values. Then read everything
and let the Syncer filter: filter_field names the field of a record,
filter_lookup_table a Lookup Table. Only
records whose value of that field is in the first column of the table are
imported, all others are skipped. The table may use the mode Table with
just one column:
service
Web Shop
Mail
The values have to be written exactly as the API delivers them. A record without the field is skipped. If the table does not exist, the import stops with an error, so it never imports nothing by accident.
The filter applies to the import and to the inventory, and also to JSON files.
JSON File
Like for Rest API, everthing is configured in an Account. Here, you just need to set the Path to the File. Fields like hostname_field are described above in the description of Rest API
When Using the data_key
The data_key can be confusing. Here two examples to see what it's for.
In this Example, data_key needs to be 'results'
{'results': [{data},{data}]}
In this case, the data key needs to be empty
[{data},{data}]