HPE GreenLake for Tags developer guide

The examples in this guide help you start using the Tags APIs to view and filter tags and tagged resources using this service.

Prerequisites

Endpoints

Endpoints are the host URLs that you submit your API requests to. The HPE GreenLake for Tags APIs use the following endpoint:

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

URIs

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

  • /tags/v1beta1/tags
  • /tags/v1beta1/tag-resources

Access and permissions

You need the correct permissions to use the HPE GreenLake Tags APIs.

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

  • GET /tags/v1beta1/tags
  • GET /tags/v1beta1/tag-resources

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 Tags API, proceed as follows:

  1. Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
  2. Go to Manage Workspace > API > Create Credentials .
  3. Select HPE GreenLake Platform from the Select 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.
  4. Enter the Credential Name .
  5. Click Create Credential .

Making It All Work

Get tags of a workspace

Review a list of the tags managed in a workspace.

Copy
Copied
GET https://global.api.greenlake.hpe.com/tags/v1beta1/tags

The following information is returned in the response:

  • id
  • type
  • key
  • value
  • resourceCount
  • and more

You can use query parameters with the Get tags of 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.

Find more information and examples in the API reference.

Get tagged resources of a workspace

Review a list of the tagged resources managed in a workspace.

Copy
Copied
GET https://global.api.greenlake.hpe.com/tags/v1beta1/tag-resources

The following information is returned in the response:

  • id
  • type
  • resourceUri
  • resourceType
  • tags
  • and more

You can use query parameters with the Get tagged resources of 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.

Find more information and examples 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 where the resource type is DEVICE_SUBSCRIPTION.

Copy
Copied
GET <URI>?filter=resourceType eq 'DEVICE_SUBSCRIPTION'

Filtering on a single property

Copy
Copied
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:

Property Example Description
Key key eq 'STIQQ4L04' Returns results when the property, key, is exactly the value to the right of eq.

Operation evaluated. Operations compare properties against literals, for example, eq. Currently, the operation is always in the middle part of a filter expression for this service.

Examples of operations:

Operation Definition
eq The property exactly matches the literal, for example, key eq 'STIQQ4L04'.
ne The property matches any literal but the specified one.

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): key eq 'STIQQ4L04' and value eq 'Checked'
  • Require either (or): key eq 'STIQQ4L04' or id eq 'd725b07f-cc56-5923-826c-6098dd3abdba'

OData filtering reference

This filtering is a subset of OData 4.0 filtering.