Creating a Client Application Using the Asynchronous Analytical Reporting API
Use this procedure to create a client application using the asynchronous analytical reporting API. Choose the asynchronous usage for larger projects.
Context
Procedure
For the first page of results, follow these steps:
- Choose a view template. If necessary, you can browse existing view templates using the GET /viewTemplates endpoint of the Analytical Reporting - View Management API.
GET {{runtime_url}}/viewTemplates?realm={realm}&product=analytics - Optional. You can find out how many records will be included in the results set for a query using the specified view template and filters using the GET /views/{viewTemplateName}/count endpoint of the Analytical Reporting - Synchronous API.
GET {{runtime_url}}/views/{template_name}/count?realm={realm}&filters={filter_list}The response includes the following fields:- count
- The total number of records that would be included in the results set using the specified view template and filters.
- MaxRecordsInEachPage
- The maximum number of records that can be returned in a single page of results. Note that a page might contain fewer records that this maximum.
- TotalPages
- The total number of pages in the results set.
- Post the initial request to the jobs queue, using the POST /jobs endpoint of the Analytical Reporting - Job Submission API, specifying the desired view and request ID.
POST {{runtime_url}}/jobs?realm={realm} Request body:{ "viewTemplateName":"ChosenViewName", "filters":{filter_list}, "requestID":"myRequestID" }The response includes the following fields:- requestID
- The request ID you specified in the requestID parameter.
- jobID
- A system-generated job ID.
- Request the status of your job using the GET /jobs/{jobId} endpoint of the Analytical Reporting - Job Results API. This request returns the job status.
GET {{runtime_url}}/jobs/{job_id}?realm={realm}This returns the job status, which can be one of the following:-
In progress
-
Failed
-
Successful
-
Expired
- files
- A list of file IDs for the first page of files in your results set. Use these as the value of the fileID parameter in queries to download each file.
- pageToken
- A token you can pass as the value of the pageToken parameter in a subsequent query to request the next page of results.
- requestID
- The request ID you specified in the requestID parameter when you posted this job.
- TotalNumOfRecords
- The approximate total number of records in the response set, including records in the current response and all other responses that belong to the current results set.
- CurrentPageRecordsCount
- The number of records included in the current page.
- TotalNumOfPages
- The total number of pages associated with the current results set.
- CurrentPageNum
- The number of the current page in the sequence of pages associated with the current results set. The response to the initial POST /jobs query is 1.
- TotalNumOfFiles
- Records are returned in the form of links to ZIP files, with each ZIP file containing up to the maximum permitted number of records. This field indicates the total number of ZIP file links in the results set.
- FilesInCurrentPage
- This field indicates the total number of ZIP file links in the current page.
-
- Request files one at a time using the GET /jobs/{jobId}/files/{fileId} endpoint of the Analytical Reporting - Job Results API.
GET {{runtime_url}}/jobs/{job_id}/files/{file_id}?realm={realm}Files are returned in ZIP format. Repeat this step for all desired file IDs.
For subsequent pages, follow these steps:
- Post the request for the next page of results to the jobs queue, using the POST /jobs endpoint of the Analytical Reporting - Job Submission API, adding the page token returned in the response to the previous GET /jobs/{jobID} query:
POST {{runtime_url}}/jobs?pageToken={pageToken}&realm={realm} Request body:{ "viewTemplateName":"ChosenViewName", "filters":{filter_list}, "requestID":"myRequestID" } - Request the status of your job, using the GET /jobs/{jobID} of the Analytical Reporting - Job Results API:
GET {{runtime_url}}/jobs/{jobID}?realm={realm}The response includes the file IDs for the specified page in the files block, and the page token for the next page of results in the pageToken field. - Request files one at a time using the /jobs/{jobId}/files/{fileId} endpoint of the Analytical Reporting - Job Results API:
GET {{runtime_url}}/jobs/{jobID}/files/{fileID}?realm={realm}Repeat this step for all desired file IDs. - Repeat this procedure until you reach the final page of results. When you reach the last page of results, the value of the pageToken field returned by the GET /jobs/{jobID} query is NULL because there are no subsequent pages in the response set.