Help Center> Cloud Stream Service> API Reference> Getting Started
View PDF

Getting Started

This section describes how to use CS APIs. Calling APIs to manage a cluster is used as example. The cluster management procedure is as follows:

  1. Obtain the user token, which will be put into the request header for authentication in a subsequent request. For details about how to obtain the token, see Authentication.
  2. Call the API for creating a SQL job to submit a streaming SQL job in POST mode. For details, see Creating a SQL Job.
  3. Call the API for running jobs. For details, see Running a Job.
  4. Call the API for querying the job list to obtain job information. For details, see Querying the List of Jobs.
  5. Call the API for stopping jobs. For details, see Stopping a Job.

Prerequisites

Cluster Management

The following values are examples (replace them based on the actual situation).

  • IAM endpoint: iam_endpoint
  • CS endpoint: cs_endpoint
  • Project ID: 9bc552e6-19af-4326-800d-281a92984636

Perform the following operations to manage the clusters:

  1. Before calling other APIs, obtain the token and set it as an environment variable. 

    curl -H "Content-Type:application/json" https://{iam_endpoint}/v3/auth/tokens -X POST -d '{ 
    "auth": { 
        "identity": { 
            "methods": [ 
                "password" 
            ], 
            "password": { 
                "user": { 
                    "name": "testname", 
                    "domain": { 
                        "name": "testname" 
                    }, 
                    "password": "Passw0rd" 
                } 
            } 
        }, 
        "scope": { 
            "project": { 
                "name": "cn-north-1" 
               
                
                 
            } 
        } 
    } 
}' -v -k
    1. Obtain the value of X-Subject-Token (indicating the Token) from the response header. The following is an example: 
      X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
    2. Run the following command to set the token as an environment variable:

      export Token={X-Subject-Token}

      X-Subject-Token is the token obtained in the preceding step. The following is an example command:

      export X-Auth-Token=MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...

  2. Call the API for creating a SQL job. 

    curl -X POST -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" -d '
{
    "name": "my job",
    "desc": "This is a job used for counting characters.",
    "sql_body": "select * from source_table",
    "run_mode": "shared_cluster",
    "spu_number": 1,
    "parallel_number": 1,
    "checkpoint_enabled": false,
    "checkpoint_mode": "exactly_once",
    "checkpoint_interval": 0,
    "log_enabled": false
}' https://{cs_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/sql_job -v -k

    The response is as follows:

    STATUS CODE 200 
{
    "message_id": "CS.12000",
    "message": "A CS job is created successfully.",
    "payload": {
        "job_id": 50320,
        "status_name": "job_init",
        "status_desc": ""
    },
    "current_time": 1533686888000
}

  3. Call the API for running jobs. 

    curl -X POST -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" -d '[50320]
' https://{cs_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/job/run -v -k

    The response is as follows:

    STATUS CODE 200 
{
    "message_id": "CS.12000",
    "message": "A CS job is created successfully.",
    "payload": {
        "job_id": 50320,
        "status_name": "job_init",
        "status_desc": ""
    },
    "current_time": 1533686888000
}

  4. Call the API for querying the job list to obtain job information. 

    curl -X GET -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" https://{cs_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/jobs -k –v

    The response is as follows:

    {
    "message_id": "CS.23000",
    "message": "Querying of the job list succeeds.",
    "payload": {
        "total": 1,
        "jobs": [
            {
                "job_id": 50320,
                "user_id": "ac4eaa303639409c8ab099d55eb1538e",
                "cluster_id": 100000,
                "project_id": "5a3314075bfa49b9ae360f4ecd333695",
                "name": "my job",
                "desc": "This is a job used for counting characters.",
                "sql_body": "",
                "run_mode": "shared_cluster",
                "job_type": "flink_jar_job",
                "spu_number": 1,
                "parallel_number": 1,
                "job_config": {
                    "checkpoint_enabled": false,
                    "checkpoint_interval": 10,
                    "checkpoint_mode": "exactly_once",
                    "log_enabled": false
                },
                "status": "job_running",
                "status_desc": "",
                "create_time": 1516952710040,
                "update_time": 1516952770835
            }
        ]
    },
    "current_time": 1533686888000
}

    If status is job_submitting, the job is being submitted. If status is job_running, the job is running.

  5. Call the API for stopping jobs. 

    curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:$Token"  -d '[50320]'
 https://{cs_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/job/stop -k -v

    The response is as follows:

    [ {   "message_id": "CS.16000",   "message": "The CS job stops successfully.",   "current_time": 1533686888000 } ]