gRPC-Streamer Plugin REST API

Authentication

The following authentication types are supported: 

• basic (/ufmRest)

• token (/ufmRestV3)

Create a Session to UFM from gRPC

Description: Creates a session to receive REST API results from the gRPC server. After a stream or submitting a call once, the session is deleted so that the authorizations are not saved by the server.

• Call: CreateSession in the gRPC

• Request Content Type: message SessionAuth

• Request Data: 

  message SessionAuth{
    string job_id=1;
    string username = 2;
    string password = 3;
    optional string token = 4;
  }
  

  
  

  • Job_id - A unique identifier for the client

  • Username - Basic authentication username 

  • Password – Basic authentication password

  • Token – The authentication token 

• Response content type: 

  message SessionRespond{
    string respond=1;
  }
  

• Respond types:

  • Success – Ok.

  • ConnectionError – UFM connection error (bad parameters or UFM is down).

  • Other exceptions – Details sent in the response.

• Console command: 

  client session --server_ip=server_ip --id=client_id --auth=username,password --token=token
  

Create a New Subscription

• Description: Only after the server has an established session for this gRPC client, the server adds all the requested REST APIs with intervals and delta requests.

• Call:

  AddSubscriber

• Request Content Type – Message SubscriberParams

• Request Data:

  message SubscriberParams{
    message APIParams {
      string ufm_api_name = 1;
      int32 interval = 2;
      optional bool only_delta = 3;
    }
    string job_id = 1;
    repeated APIParams apiParams = 2;
  } 
  

  
  

  • Job_id – A unique identifier of this subscriber

  • apiParams – A list of apiParams from the message above

  • ufm_api_name – A name from the supported REST API list of names

  • interval – The interval (in seconds) between messages that the server sends in a stream run

  • only_delta – Receive the difference between the previous messages in a stream run

• Response content type: 

  message SessionRespond{
    string respond=1;
  }
  

• Response types:

  • Created user with session and added a new IP address – Ok.

  • Cannot add subscriber without an established session – need to create a session before creating a subscriber.

  • The server already has the ID – need to create a new session and a new subscriber with a unique ID.

• Console command: 

  client create --server_ip=localhost --id=client_id --apis=events;40;True,links,alarms;10
  

  
  

  • The list of APIs is separated by commas, and the modifiers of each REST API is separated by a semi comma.

  • If the modifiers are not provided, the server uses default ones (where only_delta is False and interval is based on the API).

Edit a Known Subscription

• Description: Changes a known IP address, even if the IP address exists on the server or not.

• Call:

  AddSubscriber

• Request Content Type: Message SubscriberParams

• Request Data: 

  message SubscriberParams{
    message APIParams {
      string ufm_api_name = 1;
      int32 interval = 2;
      optional bool only_delta = 3;
    }
    string job_id = 1; //unique identifier for this job
    repeated APIParams apiParams = 2;
  } 
  

  
  

  • Job_id – A unique identifier of this subscriber.

  • apiParams – The list of apiParams from the above message

  • ufm_api_name – A name from the supported REST API list of names

  • interval – The interval in seconds between messages that the server sends in a stream run

  • only_delta – Receives only the difference between the previous messages in a stream run

• Response content type: 

  message SessionRespond{
    string respond=1;
  }
  

• Response Types:

  • Created a user with a session and added a new IP address – Ok. 

  • Cannot add subscriber that does not have a session – need to create a session before creating a subscriber.

  • Cannot add subscriber illegal APIs – cannot create subscriber with empty API list, call again with correct API list.

Get a List of Known Subscribers

• Description: Gets a list of subscribers including the requested API lists.

• Call: ListSubscribers

• Request Content Type: google.protobuf.Empty

• Response: 

  message ListSubscriberParams{
    repeated SubscriberParams subscribers = 1;
  } 
  

• Console command: server subscribes –-server_ip=server_ip

Delete a Known Subscriber

• Description: Deletes the subscriber and session (if existing).

• Call: DeleteSubscriber

• Request Content Type: Message gRPCStreamerID

• Request Data: 

  message gRPCStreamerID{
  string job_id = 1;
  }
  

• Response: google.protobuf.Empty

Run a Known Subscriber Once 

• Description: Runs the Rest API list once for a known subscriber and returns the result in message runOnceRespond, and then deletes the subscriber session.

• Call: RunOnceJob

• Request Content Type: Message gRPCStreamerID

• Request Data: 

  message gRPCStreamerID{
  string job_id = 1;
  }
  

• Response content type: 

  message runOnceRespond{
    string job_id=1;
    repeated gRPCStreamerParams results = 2;
  }
  

  
  

  • Job_id- A unique identifier of the first message.

  • Results – A list of gRPCStreamerParams contains the results from each REST API list.

• Respond:

  • Job id - Cannot run a client without an established session. Empty results – no session for this client, and the client is not known to the server.

  • Job id - Cannot run a client without creating a subscriber. Empty results – a session was created for this client, but not a subscription.

  • Job_id - Could not connect to the UFM. Empty results – the gRPC server cannot connect to the UFM machine and receive empty results, because it cannot create a subscriber with an empty API list. This means that the UFM machine has a problem or is shut down.

  • Job_id - The first unique identifier of the messages, and not empty results – Ok.

• Console command: 

  client once_id --server_ip=server_ip --id=client_id
  

Run Streamed Data of a Known Subscriber

• Description: Runs a stream of results from the Rest API list for a known subscriber and returns the result as an iterator, where each item type is a message gRPCStreamerParams. At the end, the server deletes the session.

• Call: RunStreamJob.

• Request Content Type: Message gRPCStreamerID.

• Request Data: 

  message gRPCStreamerID{
  string job_id = 1;
  }
  

• Response content type: iterator of messages gRPCStreamerParams: 

  message gRPCStreamerParams{
    string message_id = 1; // unique identifier for messages
    string ufm_api_name = 2; // what rest api receive the data from
    google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
    string data = 4; // data of rest api call
  }
  

• Response:

  • Only one message with data – no session.

  • No message – no session and/or no subscriber with this ID.

  • Messages with interval between with the modifiers – Ok.

• Console command:

  client stream_id --server_ip=server_ip --id=client_id
  

Run New Subscriber Once

• Description: After the server checks it has a session for this job ID, it runs the Rest API list for a new subscriber once and returns the result in message runOnceRespond. It does not save the subscriber ID or the session in the server.

• Call: RunOnce

• Request Content Type: Message SubscriberParams

• Request Data:

  message SubscriberParams{
    message APIParams {
      string ufm_api_name = 1;
      int32 interval = 2;
      optional bool only_delta = 3;
    }
    string job_id = 1; //unique identifier for this job
    repeated APIParams apiParams = 2;
  }
  

• Response content type:

  message runOnceRespond{
    string job_id=1;
    repeated gRPCStreamerParams results = 2;
  }
  

• Response:

  • Job id - Cannot run a client without an established session. Empty results – no session for this client.

  • Job_id - 0 – The gRPC server cannot connect to the UFM machine and receive empty results, or it cannot create a subscriber with an empty API list.

  • Job_id - The first unique identifier of the messages. Not empty results – Ok.

• Console command:

  client once --server_ip=server_ip --id=client_id --auth=username,password -–token=token --apis=events;40;True,links;20;False,alarms;10
  

• The console command also creates a session for this client.

• Either a token or basic authorization is needed.

Run Streamed Data of a New Subscriber

• Description: After the server checks it has a session for this job ID, it runs a stream of results from the Rest API list for a new subscriber and returns the result as an iterator, where each item is a message gRPCStreamerParams. At the end, it deletes the session.

• Call: RunPeriodically

• Request Content Type: Message SubscriberParams

• Request Data:

  message SubscriberParams{
    message APIParams {
      string ufm_api_name = 1;
      int32 interval = 2;
      optional bool only_delta = 3;
    }
    string job_id = 1; //unique identifier for this job
    repeated APIParams apiParams = 2;
  }
  

• Response content type: iterator of messages gRPCStreamerParams

• Response:

  • Only one message with data - Cannot run client without an established session - No session

  • Messages with intervals between with the modifiers – Ok

• Console command:

  client stream --server_ip=server_ip --id=client_id --auth=username,password -–token=token --apis=events;40;True,links;20;False,alarms;10
  

  
  

  • The console command also creates a session for the client.

  • Either a token or a basic authorization is needed.

Run a Serialization on all Running Streams

• Description: Runs a serialization for each running stream. The serialization returns results from the REST API list to each of the machines.

• Call: Serialization

• Request Content Type: protobuf.Empty

• Response: google.protobuf.Empty

Stop a Running Stream 

• Description: Cancels running streams using the client's stream ID and stops it from outside. 

• Call: StopStream

• Request Content Type: Message gRPCStreamerID

• Request Data:

  message gRPCStreamerID{
  string job_id = 1;
  }
  

• Response: google.protobuf.Empty

Run a Subscribe Stream

• Description: Creates a subscription to a client identifier. All new messages that go to that client, will be copied and also sent to this stream. 

• Call: Serialization SubscribeToStream 

• Request Content Type: message gRPCStreamerID

• Response: iterator of messages gRPCStreamerParams

  message gRPCStreamerParams{
    string message_id = 1; // unique identifier for messages
    string ufm_api_name = 2; // what rest api receive the data from
    google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
    string data = 4; // data of rest api call
  }
  

• The identifier may or may not be in the gRPC server.

• Streams cannot be stopped using StopStream.

• Console command: 

  client subscribe --server_ip=server_ip --id=client_id
  

Get Variables from a Known Subscriber

• Description: Get the variables of known subscriber (if found), else return empty variables.

• Call: GetJobParams

• Request Content Type: message gRPCStreamerID

• Response:

  message SubscriberParams{
    message APIParams {
      string ufm_api_name = 1; //currently the list of api from ufm that are supported are [Jobs, Events, Links, Alarms]
      int32 interval = 2;
      optional bool only_delta = 3;
    }
    string job_id = 1; //unique identifier for this job
    repeated APIParams apiParams = 2;
  }
  

Get Help / Version

• Description: Get help, plugin version, and information on how to interact with the server. What stages need to be done to extract the REST APIs (Session>run once/stream or Session>AddSubscriber>once_id/stream_id)

• Call: Help or Version

• Request Content Type: google.protobuf.Empty

• Response:

  message SessionRespond{
    string respond=1;
  }
  

Last updated: November 08, 2022