GRPC-Streamer Plugin

The following authentication types are supported:

• Basic (/ufmRest)

• Token (/ufmRestV3)

Description: Creates a session to receive REST API results from the UFM's GRPC server. After a stream or one call, the session is deleted so the server would not save the authorizations.

• 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 - The unique identifier for the client you want to have

• Username - The authentication username

• Password – The authentication password

• Token – The authentication token

• Response:

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

• Console command:

  Copy

  Copied!

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

• Description: Only after the server has established a session for this grpc client,add 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 subscriber identifier

• apiParams – The list of apiParams from the above message above:

• ufm_api_name – The name from the known to server request api list - TBD

• interval – The interval between messages conducted in a stream run. Presented in seconds.

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

• Response content type:

  Copy

  Copied!

              
  
              
  message SessionRespond{
    string respond=1;
  }
          

• Respond Types:

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

  • Cannot add subscriber that do no have an established session – need to create a session before creating subscriber.

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

• Console command:

  Copy

  Copied!

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

The API’s list is separated by commas, and each modifier for the REST API is separated by a semi comma.

If the server is not given a modifier, default ones are used (where only_delta is False and interval is based on the API).

• Description: Changes a known IP. Whether the server has the IP 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 – The subscriber unique identifier

• apiParams – A list of apiParams from the above message.

• TBD ufm_api_name – name from the known to server request api list

• interval – The interval between messages conducted in a stream run. Presented in seconds.

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

• Response content type:

  Copy

  Copied!

              
  
              
  message SessionRespond{
    string respond=1;
  }
          

• Respond Types:

  • Created user with new IP– Ok.

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

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

• Description: Gets the list of subscribers, including the requested list of APIs.

• 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 an existing subscriber and removes the session.

• Call: DeleteSubscriber

• Request Content Type: Message gRPCStreamerID

• Request Data:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response:protobuf.Empty

• Description: Runs the Rest API list for a known subscriber once and returns the result in message runOnceRespond, and then delete the subscriber's 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- The first message unique identifier.

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

• Responses:

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

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

  • Job_id - Cannot connect to the UFM. empty result – 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 is experiencing a problem.

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

• Console command:

  Copy

  Copied!

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

• Description: Run a stream of results from the Rest API list for a known Subscriber and return the result as interator, where each item is message gRPCStreamerParams. at the end, delete 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:

  • One message only containing "Cannot run a client without a session" – A session has not been established

  • No message – A session and/or a subscriber with this ID does not exist.

  • Messages with interval between with the modifiers – Ok

• Console command:

  Copy

  Copied!

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

• Description: After ensuring that a session for this specific job ID is established, the server runs the whole REST API list for the new subscriber once and returns the following result in message runOnceRespond. This action does not save the subscribe ID or the established 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;
  }
          

• Responses:

  • 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 messages' first unique identifier, and not an empty result – 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 creates a session for this specific client.

• A token or the basic authorization is needed, not both.

• Description: After the server checks it has a session for this job ID, Run a stream of results from the Rest API list for a new Subscriber and return the result as interator, where each item is message gRPCStreamerParams. at the end, delete 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 equals to Cant run client without 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
        

• console command also create session for that client.

• no need for both token and basic authorization, just one of them.

• Description: Run a serialization for each running stream. The serialization will return to each of the machines the results from the rest api list.

• Call: Serialization

• Request Content Type: google.protobuf.Empty

• Response: google.protobuf.Empty

• Description: Cancels running stream using the client id of the stream and stop it from outside, If found stop the stream.

• Call: StopStream

• Request Content Type: Message gRPCStreamerID

• Request Data:

  Copy

  Copied!

              
  
              
  message gRPCStreamerID{
  string job_id = 1;
  }
          

• Response: google.protobuf.Empty

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

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

• Cannot be stop streamed 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;
  }
          

Get Help / Version

• Description: Get help and the version of the plugin, 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;
  }