Networking NVIDIA UFM Enterprise REST API Guide

PKeys Monitoring REST API

Authentication

Following authentication types are supported:

  • basic (/ufmRest)

  • client (/ufmRestV2)

  • token (/ufmRestV3)

General

  • Description – allow users to query the fabric to identify GUIDs assignments to PKeys using the Actions/Jobs REST API

  • Request URL /ufmRestV2/actions/pkeys

  • Actions

    • Report a specific PKey or list of PKeys

    • Report all PKeys

    • Verify a specific PKey or list of PKeys

    • Verify all PKeys

    • Check Set GUIDs to PKey – monitor completion of a Set operation

    • Check Add GUIDs to PKey – monitor completion of an Add operation

    • Check Del GUIDs from PKey – monitor completion of a Delete operation

  • Note: All actions are performed asynchronously and require polling to provide the response when completed

  • Response to actions when started 

    <!doctype html>
    <html lang=en>
    <title>Redirecting...</title>
    <h1>Redirecting...</h1>
    <p>You should be redirected automatically to the target URL: <a href="/ufmRestV2/jobs/JOBID">/ufmRestV2/jobs/JOBID</a>. If not, click the link.
    

Jobs REST API responses

  • Description - use the jobs REST API to obtain results for actions

  • Request URL – GET /ufmRestV2/jobs/<JOBID>

  • Status codes

    • 200 - OK

    • 404 - Not Found

JSON
{
  "ID": "<JOBID>",
  "Status": "<STATUS>",
  "Progress": <PERCENT>,
  "Description": "PKeys monitoring: <ACTION> (<PKEY-DESC>)",
  "Created": "<time-stamp-1>",
  "LastUpdated": "<time-stamp-2>",
  "Summary": <RESULT>,
  "RelatedObjects": <INPUT>,
  "CreatedBy": "admin",
  "Operation": "pkeys",
  "Foreground": true,
  "SiteName": ""
}
  • <INPUT> is the JSON of the action request.

  • <ACTION> is the action name (REPORT / VERIFY / CHKADD / CHKSET / CHKDEL).

  • <PKEY-DESC> is either “PKey 0x<pkey>”, “Multiple PKeys” or “All PKeys”.

  • While Action is pending, <STATUS> is “Running”, <PERCENT> is 0 and <RESULT> is “”.

  • When Action response is ready, <STATUS> is either “Completed” or “Completed With Errors”, <PERCENT> is 100 and <RESULT> is the JSON of the result from RAMP.

NOTE: The “id” within the result JSON is an internal id used by RAMP and has no relation to the <JOBID> used to obtain action results.

Completion Status

A completed PKeys monitoring action will be reported by the job <STATUS> as completed if the result internal status is “completed” and the only GUID list shown is under “guids”.

Otherwise - the job <STATUS> will be “Completed With Errors”.

Report a Specific PKey (or List of PKeys)

  • Description – query the fabric to show which GUIDs have a specific PKey

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "REPORT"

  • Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"REPORT"

None

Name of action

Mandatory

entries

An array of objects. Each object has a "pkey" field

None

Each entry provides information about a PKey to report about

Mandatory, at least one entry

entries.pkey

Hexadecimal string between "0x0"-"0x7fff" exclusive

None

Network PKey

Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "REPORT",
             "entries": [
                 {
                     "pkey": "0x1234"
                 }
             ]
         }
    


  • Result – example of final response to query 

         {
             "id": 11,
             "action": "REPORT",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
                 }
             ]
         }
    


Report all PKeys

  • Description – query the fabric to show all PKeys and the GUIDs associated with them

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "REPORT"

  • Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"REPORT"

None

Name of action

Mandatory

all

true

None

All PKeys should be reported

Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "REPORT",
             "all": true
         }
    


  • Result – example of final response to query

         {
             "id": 12,
             "action": "REPORT",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
                 },
                 {
                     "pkey": "0x5678",
                     "guids": [ "b8cef6030083b777", "946dae03002ac111" ]
                 }
             ]
         }
    


Verify a Specific PKey (or list of PKeys)

  • Description – query the fabric to show which of the GUIDs requested to have a specific PKey were configured accordingly

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "VERIFY"

  • Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"VERIFY"

None

Name of action

Mandatory

entries

An array of objects. Each object must have a "pkey" field

None

Each entry provides information about a PKey to report about

Mandatory, at least one entry

entries.pkey

Hexadecimal string between "0x0"-"0x7fff" exclusive

None

Network PKey

Mandatory

entries.guids

["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters

[]

A list of GUIDs presumed to be associated with the PKey.

If not provided or empty, UFM will be queried to provide the list

Optional

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "VERIFY",
             "entries": [
                 {
                     "pkey": "0x1234"
                 }
             ]
         }
    


  • Result – example of final response to query 

         {
             "id": 13,
             "action": "VERIFY",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ],
                     "missing": [],
                     "wrong": []
                 }
             ]
         }
    


Verify all PKeys

  • Description – query the fabric to show for all PKeys which of the GUIDs associated with each PKey have actually been configured

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "VERIFY"

  • Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"VERIFY"

None

Name of action

Mandatory

all

true

None

All PKeys should be verified.

UFM will be queried to provide the list (PKeys and GUIDs)

Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "VERIFY",
             "all": true
         }
    


  • Result – example of final response to query 

         {
             "id": 14,
             "action": "VERIFY",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ],
                     "missing": [],
                     "wrong": []
                 },
                 {
                     "pkey": "0x5678",
                     "guids": [ "b8cef6030083b777", "946dae03002ac111" ],
                     "missing": [],
                     "wrong": []
                 }
             ]
         }
    


Monitor Setting of GUIDs to a PKey

  • Description – Monitor the setting of a group of GUIDs to a PKey

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "CHKSET"

  • Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"CHKSET"

None

Name of action

Mandatory

entry

An object with a "pkey" field and a "guids" field

None

Each entry provides information about a PKey to report about

Mandatory

entry.pkey

Hexadecimal string between "0x0"-"0x7fff" exclusive

None

Network PKey

Mandatory

entry.guids

["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters

[]

A list of GUIDs presumed to be associated with the PKey.



Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "CHKSET",
             "entry": {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             },
             "timeout": 60
         }
    


  • Result – example of final response to query 

         {
             "id": 15,
             "action": "CHKSET",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
                 }
             ]
         }
    


Monitor Adding GUIDS to a PKey

  • Description – Monitor the assignment of a group of GUIDs to a PKey

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "CHKADD"

  • Other request parameters

Name

Value

Default

Description

Mandatory/Optional

action

"CHKADD"

None

Name of action

Mandatory

entry

An object with a "pkey" field and a "guids" field

None

Each entry provides information about a PKey to report about

Mandatory

entry.pkey

Hexadecimal string between "0x0"-"0x7fff" exclusive

None

Network PKey

Mandatory

entry.guids

["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters

[]

A list of GUIDs presumed to be associated with the PKey.



Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "CHKADD",
             "entry": {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             },
             "timeout": 60
         }
    


  • Result – example of final response to query 

         {
             "id": 16,
             "action": "CHKADD",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
                 }
             ]
         }
    



Monitor Removing GUIDs from a PKey

  • Description – Monitor the removal of a group of GUIDs from a PKey

  • Request URL – POST /ufmRestV2/actions/pkeys

  • Request content type – Application/json

  • Action request parameter value – "CHKDEL"

  • Other request parameters

Name

Value

Default

Description

Mandatory/Optional

action

"CHKDEL"

None

Name of action

Mandatory

entry

An object with a "pkey" field and a "guids" field

None

Each entry provides information about a PKey to report about

Mandatory

entry.pkey

Hexadecimal string between "0x0"-"0x7fff" exclusive

None

Network PKey

Mandatory

entry.guids

["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters

[]

A list of GUIDs presumed to be associated with the PKey.



Mandatory

timeout

An integer between 1 and 200

30

Number of seconds to wait for the action to complete

Optional

  • Status Codes

    • 202 – Accepted

    • 400 – Bad Request

  • Response – "location" header contains query URL

    • Location: /ufmRestV2/jobs/<JOBID>

  • Request Data Example 

         {
             "action": "CHKDEL",
             "entry": {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             },
             "timeout": 60
         }
    


  • Result – example of final response to query 

         {
             "id": 17,
             "action": "CHKDEL",
             "status": "completed",
             "result": [
                 {
                     "pkey": "0x1234",
                     "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
                 }
             ]
         }
    


GUID lists in results

  • “guids” - a list of GUIDs that have the PKey (or in the special case of CHKDEL, GUIDs that don’t have the PKey).

  • “missing” - a list of GUIDs that should have the PKey, but unfortunately don’t have it (currently VERIFY only).

  • “wrong” - a list of GUIDs that should not have the PKey, but unfortunately do have it (currently VERIFY only).

  • “unknown” - an optional list of GUIDs that were explicitly specified in the action, but appear not to be part of the fabric.

  • “unreachable” - an optional list of GUIDs that although being part of the fabric, RAMP was unable to receive a reply to its queries.

Last updated: