gRPC-Streamer Plugin REST API

The following authentication types are supported:

• basic (/ufmRest)

• token (/ufmRestV3)

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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

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

• 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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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).

• 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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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.

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

• Call: ListSubscribers

• Request Content Type: google.protobuf.Empty

• Response:

  Copy

  Copied!

              
  
              
  message ListSubscriberParams{
    repeated SubscriberParams subscribers = 1;
  } 
          

• Console command: server subscribes –-server_ip=server_ip

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

• Call: DeleteSubscriber

• Request Content Type: Message gRPCStreamerID

• Request Data:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response: google.protobuf.Empty

• 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:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response content type:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

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

• 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:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response content type: iterator of messages gRPCStreamerParams:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

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

• 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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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.

• 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:

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

              
  
              
  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.

• 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

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

• Call: StopStream

• Request Content Type: Message gRPCStreamerID

• Request Data:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response: google.protobuf.Empty

• 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

  Copy

  Copied!

              
  
              
  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:

  Copy

  Copied!

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

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

• Call: GetJobParams

• Request Content Type: message gRPCStreamerID

• Response:

  Copy

  Copied!

              
  
              
  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;
  }
          

• 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:

  Copy

  Copied!

              
  
              
  message SessionRespond{
    string respond=1;
  }