NVIDIA UFM Enterprise REST API Guide v6.13.0
NVIDIA UFM Enterprise REST API Guide v6.13.0

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

© Copyright 2023, NVIDIA. Last updated on Sep 5, 2023.