Description
If an Alation API returns a job identifier, this API can be used to determine the status of a job. The job identifier could either be a name or an integer ID.
Since the PUT multiple Custom Field Values Async endpoint writes data to two data stores, it initiates two separate jobs. The Custom Field Values API response returns the ID of the first job. Use that ID to query the Jobs API. The response from the Jobs API returns the ID of the second job. You must track the status of each job separately.
URL
GET
/api/v1/bulk_metadata/job/?{params}
Replace {params} with one of the parameters mentioned in the URL parameters section.
URL Parameters
Name | Description |
---|---|
id | Use this parameter if the API you were using returns an integer job identifier. The value for this parameter is an integer ID. For Example: https://yourcompany.alation.com/api/v1/bulk_metadata/job/?id=1 |
name | Use this parameter if the API you were using returns a string job identifier i.e. a job name. The value for this parameter is a job name. For Example: https://yourcompany.alation.com/api/v1/bulk_metadata/job/?name=MetadataExtraction%231_2017-10-05-19-36-45-431906-00-00-4ea1dc02-1c9f-41db-be6f-3f7cb1849da3 NOTE: The following APIs return a job name: 1. Lineage API 2. Report Sources API NOTE: It is important to URL encode the job name since most of the job names contain # . |
Headers
HTTP Header | Value |
---|---|
TOKEN | <your_token> |
Replace <your_token> with your API token, which can be obtained from Get API Token.
Success Response
Content-Type: application/json
Status: 200 OK
Body
The response body will be a JSON object containing three properties: status
, msg
, and result
.
Example:
{
"status": "successful",
"msg": "Job finished in 1.0 seconds at 2017-01-12 23:52:34.307327+00:00",
"result": "{\"updated_objects\": 2, \"number_received\": 2, \"error_objects\": [], \"error\": \"\"}"
}
The three properties are described below.
status
Indicates the status of the job. Status can be one of the following:
- running - specifies that the job is not yet completed.
- successful - specifies that the job has been completed successfully.
- failed - specifies that the job has failed.
msg
Message describing the time taken to complete the job and the timestamp of job completion.
result
Contains detailed information about the job. The format of the result depends on the API that initiated the job.
The general format for most jobs will be a JSON object that has four properties:
- updated_objects - Represent the number of objects updated.
- number_received - Represents the number of objects received.
- error_objects - Contains information about any errors that might have occurred while executing the API (the one that has returned the job name) request.
- error - Specifies the number of errors ignored
If the the job was initiated with a PUT multiple Custom Field Values Async call, the result format will be a JSON object containing an array of message strings. Anytime there's an update on the status of the job, a new message will be added to the array. Since the Custom Field Values PUT endpoint writes data to two data stores, it initiates two separate jobs. Each result message for the first job indicates the job ID for the other job. You must track the status of each job separately.
Error Response
Invalid Token
Status: 401 UNAUTHORIZED
Body
{
"detail": "Authentication failed"
}
Missing Token Header
Status: 401 UNAUTHORIZED
Body
{
"detail": "Authentication credentials were not provided."
}
Code Samples
cURL
#!/bin/bash
# This is an example token. Please replace this with your token.
API_TOKEN="2abcd-4c04-4c21-8692-eda27a877f90"
BASE_URL="https://alation.yourcompany.com/api/v1/bulk_metadata/job"
# Get the status of the job returned from Lineage API
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?name=bulk_api_job_2017-09-10-17-07-04-918251-00-00-386321a8-4157-453a-8cf0-a5e68641c2ea"
# Get the status of the job returned by push QLI API
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?id=1"
Python
import requests
import json
# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}
BASE_URL = 'https://alation.yourcompany.com/api/v1/bulk_metadata/job'
# Add a url encoded job name
# Alernatively you can use urllib.quote(<job_name>) to urlencode the job name
job_name = "MetadataExtraction%231_Virtual_2017-01-12-23-52-34-272077-00-00-f11a1877-2ce7-4f6c-98e7-9bf5f8c0abf2"
# Get the details of a job with name
response = requests.get(BASE_URL + '/?name=' + job_name, headers=headers)
job_details = json.loads(response.text)
result = json.loads(job_details['result'])
print "Status: %s, Message: %s, Updated Objects: %s" % (job_details['status'], job_details['msg'], result['updated_objects'])
# Get the details of a job with integer identifier
response = requests.get(BASE_URL + '/?id=1', headers=headers)
job_details = json.loads(response.text)
print "Status: %s, Message: %s, Result: %s" % (job_details['status'], job_details['msg'], job_details['result'])
Sample Request and Response
Get the status of the job by its name
URL
GET
/api/v1/bulk_metadata/job/?name=**MetadataExtraction%231_2017-10-05-19-36-45-431906-00-00-4ea1dc02-1c9f-41db-be6f-3f7cb1849da3**
Success Response
{
"status": "successful",
"msg": "Job finished in 2.0 seconds at 2017-10-05 19:36:48.374593+00:00",
"result": "{\"updated_objects\": 1, \"number_received\": 2, \"error_objects\": [\"Line 1. Key: schema_b. Datasource id in key does not match the id in the request\"], \"error\": \"1 errors were ignored\"}"
}
Get the status of the job by its integer ID
URL
GET
/api/v1/bulk_metadata/job/?id=**1**
Success Response
{
"status": "successful",
"msg": "Job finished in 0.585993 seconds at 2017-11-30 18:59:10.445133+00:00",
"result": "Bulk Query Ingestion Succeeded: 0 new events ingested, 1 previously-ingested events skipped."
}