HPE GreenLake for Device Management developer guide

The examples in this guide help you start using the Device Management APIs to add and manage devices using this service.

Prerequisites

Endpoints

Endpoints are the host URLs that you submit your API requests to. Device Management APIs use the following endpoint:

https://global.api.greenlake.hpe.com/

URIs

Unique Resource Identifiers (URIs) identify a server or resource used in the Device Management API. A URI is a full API path ending with a specific endpoint. For example:

• /devices/v1/devices
• /devices/v1/async-operations/{id}
• /devices/v1/devices/{id}

Access and permissions

You need the correct permissions to use the HPE GreenLake Device Management APIs.

View permissions for Devices and Subscription Service (ccs.device-management.view) are required to make the following Device Management API calls:

• GET /devices/v1/devices
• GET /devices/v1/async-operations/{id}
• GET /devices/v1/devices/{id}

Edit permissions for Devices and Subscription Service (ccs.device-management.edit) are required to make the following Device Management API calls:

• POST /devices/v1/devices
• PATCH /devices/v1/devices

Generating a token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access HPE GreenLake platform Device Management API, proceed as follows:

1. Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
2. Go to Manage Workspace > Personal API clients > Create personal API client .
3. Enter a Personal API client Name .
4. Select HPE GreenLake Cloud Platform from the Service Manager drop-down. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.
5. Click Create personal API client .
6. Copy the Client ID and Client Secret .

Making It All Work

Add devices

Use this POST API request to add one or more devices to a workspace.

This API request provides an asynchronous response and returns a 202 Accepted status when input validations are successful. Use the Get the status of an asynchronous operation in devices API to view the status of this asynchronous operation. The location header in the response provides the URI to be invoked for fetching progress of the subscription addition task. Example location header: /devices/v1/async-operations/84a4e4d0-82c4-4de8-9238-69ffbcbb8ec9.

POST https://global.api.greenlake.hpe.com/devices/v1/devices

The payload:

{
  "network": [
    {
      "tags": {
        "property1": "{tag_value1}",
        "property2": "{tag_value2}"
      },
      "serialNumber": "{serial_number}",
      "macAddress": "{mac_address}"
    }
  ],
  "compute": [
    {
      "tags": {
        "property1": "{tag_value1}",
        "property2": "{tag_value2}"
      },
      "serialNumber": "{serial_number}",
      "partNumber": "{mac_address}"
    }
  ],
  "storage": [
    {
      "tags": {
        "property1": "{tag_value1}",
        "property2": "{tag_value2}"
      },
      "serialNumber": "{serial_number}",
      "subscriptionKey": "{subscription_key}"
    }
  ]
}

Get devices managed in a workspace

Get a list of devices managed in a workspace.

GET https://global.api.greenlake.hpe.com/devices/v1/devices

The following information is returned in the response:

• id
• macAddress
• serialNumber
• partNumber
• type
• deviceType
• model
• region
• and more

You can use query parameters with the Get devices managed in a workspace API:

• filter — Limit the resources operated on by an endpoint or, when used with a multiple-GET endpoint, return only the subset of resources that match the filter. View the filtering section to learn more about filtering.
• sort — Specify the order in which to return results. The value of the sort query parameter is a comma-separated list of sort expressions
• limit — Define the maximum number of records to return.

Get specific device information

Get details of a specific device associated to a workspace. Take the field id from the response of Get devices managed in a workspace API.

GET https://global.api.greenlake.hpe.com/devices/v1/devices/{id}

The following information is returned in the response:

• id
• macAddress
• serialNumber
• partNumber
• deviceType
• model
• region
• and more

Get the status of an asynchronous operation in devices

This API returns the status of the Adding devices and updating devices asynchronous API operations.

GET https://global.api.greenlake.hpe.com/devices/v1/async-operations/{id}

The following information is returned in the response:

• id
• type
• status
• startedAt
• endedAt
• progressPercent
• suggestedPollingIntervalSeconds
• timeoutMinutes
• result
• resultType

More information on this API can be found in the API reference.

Update devices

Use this PATCH API to update devices by passing one or more device IDs. Currently, this API supports:

• Assigning devices to an application.
• Removing devices from an application.
• Applying subscriptions to devices.
• Removing subscriptions from devices.

PATCH https://global.api.greenlake.hpe.com/devices/v1/devices?id={id}

The payload:

{
  "subscription": [
    {
      "id": "subscription_id"
    }
  ],
  "application": {
    "id": "application_id"
  },
  "region": "region"
}

More information can be found in the API reference

Filtering

Filters provide the ability to limit the resources that take part in the action of a REST call. When a REST call includes a filter, the GET action is restricted to a response that meets the filter requirements. Specify filters using the query parameter filter.

Filtering example

In this example of filtering, the query's resources are limited to results were the device type is COMPUTE.

GET <URI>?filter=deviceType eq 'COMPUTE'

Filtering on a single property

filter = <propertyName> <comparison operation> <literal>

Property is the name of an attribute in the requested resource type. The property name is always to the left of the operation.

For example:

Operation evaluated. Operations compare properties against literals, for example, eq. All parameters except in require the property on the left and the literal on the right. The in parameter allows the property on either side.

Examples of operations:

A literal, for example, true, is what an operation compares a property to. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

The following are examples of literals.

• String : Anything in 'single quotes'. Reserved characters in string literals must be URL encoded.
• Integer : -100, -1, 0, 1, 100
• Decimal : -3.14, -2.71, 2.71, 3.14
• Timestamp : 2019-10-12T07:20:50.52934852Z. The timestamp format is [RFC3339]
• Boolean : true, false
• Null : null. Null is equal to itself and nothing else. Null is not greater or less than anything.

Filtering on multiple properties

Logical operations facilitate filtering using multiple queries. Combine multiple operations using the operator and or or, for example:

• Require both (and): serialNumber eq 'STIQQ4L04' and deviceType eq 'STORAGE
• Require either (or): serialNumber eq 'STIQQ4L04' or deviceType eq 'STORAGE

OData filtering reference

This filtering is a subset of OData 4.0 filtering.

Find more information and examples in the API reference.