Products¶
Products define the services exposed by a Provider.
Rationale¶
Provider
s expose services into UCloud. But, different
Provider
s expose different services. UCloud uses Product
s to define the
services of a Provider
. As an example, a
Provider
might have the following services:
Storage: Two tiers of storage. Fast storage, for short-lived data. Slower storage, for long-term data storage.
Compute: Three tiers of compute. Slim nodes for ordinary computations. Fat nodes for memory-hungry applications. GPU powered nodes for artificial intelligence.
For many Provider
s, the story doesn’t stop here. You can often allocate your
Job
s on a machine “slice”. This can increase overall utilization, as users
aren’t forced to request full nodes. A Provider
might advertise the following
slices:
Name | vCPU | RAM (GB) | GPU | Price |
---|---|---|---|---|
example-slim-1 |
1 | 4 | 0 | 0,100 DKK/hr |
example-slim-2 |
2 | 8 | 0 | 0,200 DKK/hr |
example-slim-4 |
4 | 16 | 0 | 0,400 DKK/hr |
example-slim-8 |
8 | 32 | 0 | 0,800 DKK/hr |
Table: A single node-type split up into individual slices.
Concepts¶
UCloud represent these concepts in the following abstractions:
ProductType
: A classifier for aProduct
, defines the behavior of aProduct
.ProductCategory
: A group of similarProduct
s. In most cases,Product
s in a category run on identical hardware.
Below, we show an example of how a Provider
can organize their services.
Figure: All Product
s in UCloud are of a specific type, such as: STORAGE
and COMPUTE
.
Provider
s have zero or more categories of every type, e.g. example-slim
.
In a given category, the Provider
has one or more slices.
Payment Model¶
UCloud uses a flexible payment model, which allows Provider
s to use a model which
is familiar to them. In short, a Provider
must first choose one of the following payment types:
Differential models (
ChargeType.DIFFERENTIAL_QUOTA
)Quota (
ProductPriceUnit.PER_UNIT
)
Absolute models (
ChargeType.ABSOLUTE
)One-time payment (
ProductPriceUnit.PER_UNIT
andProductPriceUnit.CREDITS_PER_UNIT
)Periodic payment (
ProductPriceUnit.UNITS_PER_X
andProductPriceUnit.CREDITS_PER_X
)
📝 NOTE: To select a model, you must specify a ChargeType
and a ProductPriceUnit
. We have
shown all valid combinations above.
Quotas put a strict limit on the “number of units” in concurrent use. UCloud measures this number in a
Product
specific way. A unit is pre-defined and stable across the entirety of UCloud. A few quick
examples:
Storage: Measured in GB (10⁹ bytes. 1 byte = 1 octet)
Compute: Measured in hyper-threaded cores (vCPU)
Public IPs: Measured in IP addresses
Public links: Measured in public links
If using an absolute model, then you must choose the unit of allocation:
You specify allocations in units (
UNITS_PER_X
). For example: 3000 IP addresses.You specify allocations in money (
CREDITS_PER_X
). For example: 1000 DKK.
📝 NOTE: For precision purposes, UCloud specifies all money sums as integers. As a result, 1 UCloud credit is equal to one millionth of a Danish Crown (DKK).
When using periodic payments, you must also specify the length of a single period. Provider
s are not required to
report usage once for every period. But the reporting itself must specify usage in number of periods.
UCloud supports period lengths of a minute, one hour and one day.
Understanding the price¶
All Product
s have a pricePerUnit
property:
The
pricePerUnit
specifies the cost of a single unit in a single period.Products not paid with credits must have a
pricePerUnit
of 1. Quotas and one-time payments are always made for a single “period”.
This can lead to some surprising results when defining compute products. Let’s consider the example from the beginning:
Name | vCPU | RAM (GB) | GPU | Price |
---|---|---|---|---|
example-slim-1 |
1 | 4 | 0 | 0,100 DKK/hr |
example-slim-2 |
2 | 8 | 0 | 0,200 DKK/hr |
example-slim-4 |
4 | 16 | 0 | 0,400 DKK/hr |
example-slim-8 |
8 | 32 | 0 | 0,800 DKK/hr |
Table: Human-readable compute products.
When implementing this in UCloud, a Provider might naively set the following prices:
Name | ChargeType | ProductPriceUnit | Price |
---|---|---|---|
example-slim-1 |
ABSOLUTE |
CREDITS_PER_HOUR |
100_000 |
example-slim-2 |
ABSOLUTE |
CREDITS_PER_HOUR |
200_000 |
example-slim-4 |
ABSOLUTE |
CREDITS_PER_HOUR |
400_000 |
example-slim-8 |
ABSOLUTE |
CREDITS_PER_HOUR |
800_000 |
Table: ️⚠️ Incorrect implementation of prices in UCloud ️⚠️
This is wrong. UCloud defines the price as the cost of using a single unit in a single period. The “unit of use”
for a compute product is a single vCPU. Thus, a correct Provider
implementation would over-report the usage by a
factor equal to the number of vCPUs in the machine. Instead, the price must be based on a single vCPU:
Name | ChargeType | ProductPriceUnit | Price |
---|---|---|---|
example-slim-1 |
ABSOLUTE |
CREDITS_PER_HOUR |
100_000 |
example-slim-2 |
ABSOLUTE |
CREDITS_PER_HOUR |
100_000 |
example-slim-4 |
ABSOLUTE |
CREDITS_PER_HOUR |
100_000 |
example-slim-8 |
ABSOLUTE |
CREDITS_PER_HOUR |
100_000 |
Table: ✅ Correct implementation of prices in UCloud ✅
Table of Contents¶
1. Examples
Description |
---|
Browse all available products |
Browse products by type |
Retrieve a single product |
2. Remote Procedure Calls
Name | Description |
---|---|
browse |
Browse a set of products |
retrieve |
Retrieve a single product |
create |
Creates a new [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md) in UCloud |
3. Data Models
Name | Description |
---|---|
ChargeType |
No description |
Product |
Products define the services exposed by a Provider. |
Product.Compute |
A compute Product |
Product.Ingress |
An ingress Product |
Product.License |
A license Product |
Product.NetworkIP |
An IP address Product |
Product.Storage |
A storage Product |
ProductCategoryId |
No description |
ProductPriceUnit |
No description |
ProductReference |
Contains a unique reference to a Product |
ProductType |
A classifier for a [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md) |
ProductsBrowseRequest |
The base type for requesting paginated content. |
ProductsRetrieveRequest |
No description |
Example: Browse all available products¶
Frequency of use | Common |
---|---|
Actors |
|
Communication Flow: Kotlin
Products.browse.call(
ProductsBrowseRequest(
consistency = null,
filterArea = null,
filterCategory = null,
filterName = null,
filterProvider = null,
filterVersion = null,
includeBalance = null,
itemsPerPage = 50,
itemsToSkip = null,
next = null,
showAllVersions = null,
),
user
).orThrow()
/*
PageV2(
items = listOf(Product.Compute(
category = ProductCategoryId(
id = "example-compute",
name = "example-compute",
provider = "example",
),
chargeType = ChargeType.ABSOLUTE,
cpu = 10,
cpuModel = null,
description = "An example compute product",
freeToUse = false,
gpu = 0,
gpuModel = null,
hiddenInGrantApplications = false,
memoryInGigs = 20,
memoryModel = null,
name = "example-compute",
pricePerUnit = 1000000,
priority = 0,
productType = ProductType.COMPUTE,
unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE,
version = 1,
balance = null,
id = "example-compute",
), Product.Storage(
category = ProductCategoryId(
id = "example-storage",
name = "example-storage",
provider = "example",
),
chargeType = ChargeType.DIFFERENTIAL_QUOTA,
description = "An example storage product (Quota)",
freeToUse = false,
hiddenInGrantApplications = false,
name = "example-storage",
pricePerUnit = 1,
priority = 0,
productType = ProductType.STORAGE,
unitOfPrice = ProductPriceUnit.PER_UNIT,
version = 1,
balance = null,
id = "example-storage",
)),
itemsPerPage = 50,
next = null,
)
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------
# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50"
# {
# "itemsPerPage": 50,
# "items": [
# {
# "type": "compute",
# "balance": null,
# "name": "example-compute",
# "pricePerUnit": 1000000,
# "category": {
# "name": "example-compute",
# "provider": "example"
# },
# "description": "An example compute product",
# "priority": 0,
# "cpu": 10,
# "memoryInGigs": 20,
# "gpu": 0,
# "cpuModel": null,
# "memoryModel": null,
# "gpuModel": null,
# "version": 1,
# "freeToUse": false,
# "unitOfPrice": "CREDITS_PER_MINUTE",
# "chargeType": "ABSOLUTE",
# "hiddenInGrantApplications": false,
# "productType": "COMPUTE"
# },
# {
# "type": "storage",
# "balance": null,
# "name": "example-storage",
# "pricePerUnit": 1,
# "category": {
# "name": "example-storage",
# "provider": "example"
# },
# "description": "An example storage product (Quota)",
# "priority": 0,
# "version": 1,
# "freeToUse": false,
# "unitOfPrice": "PER_UNIT",
# "chargeType": "DIFFERENTIAL_QUOTA",
# "hiddenInGrantApplications": false,
# "productType": "STORAGE"
# }
# ],
# "next": null
# }
Communication Flow: Visual
Example: Browse products by type¶
Frequency of use | Common |
---|---|
Actors |
|
Communication Flow: Kotlin
Products.browse.call(
ProductsBrowseRequest(
consistency = null,
filterArea = ProductType.COMPUTE,
filterCategory = null,
filterName = null,
filterProvider = null,
filterVersion = null,
includeBalance = null,
itemsPerPage = 50,
itemsToSkip = null,
next = null,
showAllVersions = null,
),
user
).orThrow()
/*
PageV2(
items = listOf(Product.Compute(
category = ProductCategoryId(
id = "example-compute",
name = "example-compute",
provider = "example",
),
chargeType = ChargeType.ABSOLUTE,
cpu = 10,
cpuModel = null,
description = "An example compute product",
freeToUse = false,
gpu = 0,
gpuModel = null,
hiddenInGrantApplications = false,
memoryInGigs = 20,
memoryModel = null,
name = "example-compute",
pricePerUnit = 1000000,
priority = 0,
productType = ProductType.COMPUTE,
unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE,
version = 1,
balance = null,
id = "example-compute",
)),
itemsPerPage = 50,
next = null,
)
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------
# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50&filterArea=COMPUTE"
# {
# "itemsPerPage": 50,
# "items": [
# {
# "type": "compute",
# "balance": null,
# "name": "example-compute",
# "pricePerUnit": 1000000,
# "category": {
# "name": "example-compute",
# "provider": "example"
# },
# "description": "An example compute product",
# "priority": 0,
# "cpu": 10,
# "memoryInGigs": 20,
# "gpu": 0,
# "cpuModel": null,
# "memoryModel": null,
# "gpuModel": null,
# "version": 1,
# "freeToUse": false,
# "unitOfPrice": "CREDITS_PER_MINUTE",
# "chargeType": "ABSOLUTE",
# "hiddenInGrantApplications": false,
# "productType": "COMPUTE"
# }
# ],
# "next": null
# }
Communication Flow: Visual
Example: Retrieve a single product¶
Frequency of use | Common |
---|---|
Actors |
|
Communication Flow: Kotlin
Products.retrieve.call(
ProductsRetrieveRequest(
filterArea = null,
filterCategory = "example-compute",
filterName = "example-compute",
filterProvider = "example",
filterVersion = null,
includeBalance = null,
),
user
).orThrow()
/*
Product.Compute(
category = ProductCategoryId(
id = "example-compute",
name = "example-compute",
provider = "example",
),
chargeType = ChargeType.ABSOLUTE,
cpu = 10,
cpuModel = null,
description = "An example compute product",
freeToUse = false,
gpu = 0,
gpuModel = null,
hiddenInGrantApplications = false,
memoryInGigs = 20,
memoryModel = null,
name = "example-compute",
pricePerUnit = 1000000,
priority = 0,
productType = ProductType.COMPUTE,
unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE,
version = 1,
balance = null,
id = "example-compute",
)
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------
# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/retrieve?filterName=example-compute&filterCategory=example-compute&filterProvider=example"
# {
# "type": "compute",
# "balance": null,
# "name": "example-compute",
# "pricePerUnit": 1000000,
# "category": {
# "name": "example-compute",
# "provider": "example"
# },
# "description": "An example compute product",
# "priority": 0,
# "cpu": 10,
# "memoryInGigs": 20,
# "gpu": 0,
# "cpuModel": null,
# "memoryModel": null,
# "gpuModel": null,
# "version": 1,
# "freeToUse": false,
# "unitOfPrice": "CREDITS_PER_MINUTE",
# "chargeType": "ABSOLUTE",
# "hiddenInGrantApplications": false,
# "productType": "COMPUTE"
# }
Communication Flow: Visual
Remote Procedure Calls¶
browse
¶
Browse a set of products
Request | Response | Error |
---|---|---|
ProductsBrowseRequest |
PageV2<Product> |
CommonErrorMessage |
This endpoint uses the normal pagination and filter mechanisms to return a list of Product
.
Examples:
Example |
---|
Browse in the full product catalog |
Browse for a specific type of product (e.g. compute) |
retrieve
¶
Retrieve a single product
Request | Response | Error |
---|---|---|
ProductsRetrieveRequest |
Product |
CommonErrorMessage |
Examples:
Example |
---|
Retrieving a single product by ID |
create
¶
Creates a new Product
in UCloud
Request | Response | Error |
---|---|---|
BulkRequest<Product> |
Unit |
CommonErrorMessage |
Only providers and UCloud administrators can create a Product
. When this endpoint is
invoked by a provider, then the provider field of the Product
must match the invoking user.
The Product
will become ready and visible in UCloud immediately after invoking this call.
If no Product
has been created in this category before, then this category will be created.
📝 NOTE: Most properties of a ProductCategory
are immutable and must not be changed.
As a result, you cannot create a new Product
later with different category properties.
If the Product
already exists, then a new version
of it is created. Version numbers are
always sequential and the incoming version number is always ignored by UCloud.
Data Models¶
ChargeType
¶
enum class ChargeType {
ABSOLUTE,
DIFFERENTIAL_QUOTA,
}
Properties
ABSOLUTE
DIFFERENTIAL_QUOTA
Product
¶
Products define the services exposed by a Provider.
sealed class Product {
abstract val balance: Long?
abstract val category: ProductCategoryId
abstract val chargeType: ChargeType
abstract val description: String
abstract val freeToUse: Boolean
abstract val hiddenInGrantApplications: Boolean
abstract val id: String
abstract val name: String
abstract val pricePerUnit: Long
abstract val priority: Int
abstract val productType: ProductType
abstract val unitOfPrice: ProductPriceUnit
abstract val version: Int
class Compute : Product()
class Ingress : Product()
class License : Product()
class NetworkIP : Product()
class Storage : Product()
}
For more information see this page.
Properties
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
chargeType
: ChargeType
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType
description
: String
A short (single-line) description of the Product
String
freeToUse
: Boolean
Indicates that a Wallet is not required to use this Product
Boolean
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
hiddenInGrantApplications
: Boolean
Flag to indicate that this Product is not publicly available
Boolean
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
id
: String
String
name
: String
A unique name associated with this Product
String
priority
: Int
A integer used for changing the order in which products are displayed (ascending order)
Int
productType
: ProductType
Classifier used to explain the type of Product
ProductType
unitOfPrice
: ProductPriceUnit
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit
version
: Int
This property is no longer used.
Int
Product.Compute
¶
A compute Product
data class Compute(
val name: String,
val pricePerUnit: Long,
val category: ProductCategoryId,
val description: String?,
val priority: Int?,
val cpu: Int?,
val memoryInGigs: Int?,
val gpu: Int?,
val cpuModel: String?,
val memoryModel: String?,
val gpuModel: String?,
val version: Int?,
val freeToUse: Boolean?,
val unitOfPrice: ProductPriceUnit?,
val chargeType: ChargeType?,
val hiddenInGrantApplications: Boolean?,
val productType: ProductType,
val balance: Long?,
val id: String,
val type: String /* "compute" */,
)
Unit |
API |
---|---|
Measured in hyper-threaded cores (vCPU) |
Properties
name
: String
A unique name associated with this Product
String
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
description
: String?
A short (single-line) description of the Product
String?
priority
: Int?
A integer used for changing the order in which products are displayed (ascending order)
Int?
cpu
: Int?
Int?
memoryInGigs
: Int?
Int?
gpu
: Int?
Int?
cpuModel
: String?
String?
memoryModel
: String?
String?
gpuModel
: String?
String?
version
: Int?
This property is no longer used.
Int?
freeToUse
: Boolean?
Indicates that a Wallet is not required to use this Product
Boolean?
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
unitOfPrice
: ProductPriceUnit?
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit?
chargeType
: ChargeType?
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType?
hiddenInGrantApplications
: Boolean?
Flag to indicate that this Product is not publicly available
Boolean?
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
productType
: ProductType
ProductType
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
id
: String
String
type
: String /* "compute" */
The type discriminator
String /* "compute" */
Product.Ingress
¶
An ingress Product
data class Ingress(
val name: String,
val pricePerUnit: Long,
val category: ProductCategoryId,
val description: String?,
val priority: Int?,
val version: Int?,
val freeToUse: Boolean?,
val unitOfPrice: ProductPriceUnit?,
val chargeType: ChargeType?,
val hiddenInGrantApplications: Boolean?,
val productType: ProductType,
val balance: Long?,
val id: String,
val type: String /* "ingress" */,
)
Unit |
API |
---|---|
Measured in number of ingresses |
Properties
name
: String
A unique name associated with this Product
String
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
description
: String?
A short (single-line) description of the Product
String?
priority
: Int?
A integer used for changing the order in which products are displayed (ascending order)
Int?
version
: Int?
This property is no longer used.
Int?
freeToUse
: Boolean?
Indicates that a Wallet is not required to use this Product
Boolean?
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
unitOfPrice
: ProductPriceUnit?
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit?
chargeType
: ChargeType?
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType?
hiddenInGrantApplications
: Boolean?
Flag to indicate that this Product is not publicly available
Boolean?
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
productType
: ProductType
ProductType
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
id
: String
String
type
: String /* "ingress" */
The type discriminator
String /* "ingress" */
Product.License
¶
A license Product
data class License(
val name: String,
val pricePerUnit: Long,
val category: ProductCategoryId,
val description: String?,
val priority: Int?,
val tags: List<String>?,
val version: Int?,
val freeToUse: Boolean?,
val unitOfPrice: ProductPriceUnit?,
val chargeType: ChargeType?,
val hiddenInGrantApplications: Boolean?,
val productType: ProductType,
val balance: Long?,
val id: String,
val type: String /* "license" */,
)
Unit |
API |
---|---|
Measured in number of licenses |
Properties
name
: String
A unique name associated with this Product
String
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
description
: String?
A short (single-line) description of the Product
String?
priority
: Int?
A integer used for changing the order in which products are displayed (ascending order)
Int?
version
: Int?
This property is no longer used.
Int?
freeToUse
: Boolean?
Indicates that a Wallet is not required to use this Product
Boolean?
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
unitOfPrice
: ProductPriceUnit?
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit?
chargeType
: ChargeType?
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType?
hiddenInGrantApplications
: Boolean?
Flag to indicate that this Product is not publicly available
Boolean?
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
productType
: ProductType
ProductType
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
id
: String
String
type
: String /* "license" */
The type discriminator
String /* "license" */
Product.NetworkIP
¶
An IP address Product
data class NetworkIP(
val name: String,
val pricePerUnit: Long,
val category: ProductCategoryId,
val description: String?,
val priority: Int?,
val version: Int?,
val freeToUse: Boolean?,
val unitOfPrice: ProductPriceUnit?,
val chargeType: ChargeType?,
val hiddenInGrantApplications: Boolean?,
val productType: ProductType,
val balance: Long?,
val id: String,
val type: String /* "network_ip" */,
)
Unit |
API |
---|---|
Measured in number of IP addresses |
Properties
name
: String
A unique name associated with this Product
String
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
description
: String?
A short (single-line) description of the Product
String?
priority
: Int?
A integer used for changing the order in which products are displayed (ascending order)
Int?
version
: Int?
This property is no longer used.
Int?
freeToUse
: Boolean?
Indicates that a Wallet is not required to use this Product
Boolean?
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
unitOfPrice
: ProductPriceUnit?
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit?
chargeType
: ChargeType?
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType?
hiddenInGrantApplications
: Boolean?
Flag to indicate that this Product is not publicly available
Boolean?
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
productType
: ProductType
ProductType
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
id
: String
String
type
: String /* "network_ip" */
The type discriminator
String /* "network_ip" */
Product.Storage
¶
A storage Product
data class Storage(
val name: String,
val pricePerUnit: Long,
val category: ProductCategoryId,
val description: String?,
val priority: Int?,
val version: Int?,
val freeToUse: Boolean?,
val unitOfPrice: ProductPriceUnit?,
val chargeType: ChargeType?,
val hiddenInGrantApplications: Boolean?,
val productType: ProductType,
val balance: Long?,
val id: String,
val type: String /* "storage" */,
)
Unit |
API |
---|---|
Measured in GB (10⁹ bytes. 1 byte = 1 octet) |
Properties
name
: String
A unique name associated with this Product
String
category
: ProductCategoryId
The category groups similar products together, it also defines which provider owns the product
ProductCategoryId
description
: String?
A short (single-line) description of the Product
String?
priority
: Int?
A integer used for changing the order in which products are displayed (ascending order)
Int?
version
: Int?
This property is no longer used.
Int?
freeToUse
: Boolean?
Indicates that a Wallet is not required to use this Product
Boolean?
Under normal circumstances, a Wallet
is always required. This is required even if a Product
has a pricePerUnit
of 0. If freeToUse = true
then the Wallet requirement is dropped.
unitOfPrice
: ProductPriceUnit?
The unit of price. Used in combination with chargeType to create a complete payment model.
ProductPriceUnit?
chargeType
: ChargeType?
The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
ChargeType?
hiddenInGrantApplications
: Boolean?
Flag to indicate that this Product is not publicly available
Boolean?
⚠️ WARNING: This doesn’t make the Product
secret. In only hides the Product
from the grant
system’s UI.
productType
: ProductType
ProductType
balance
: Long?
Included only with certain endpoints which support `includeBalance`
Long?
id
: String
String
type
: String /* "storage" */
The type discriminator
String /* "storage" */
ProductCategoryId
¶
data class ProductCategoryId(
val name: String,
val provider: String,
val id: String,
)
ProductPriceUnit
¶
enum class ProductPriceUnit {
CREDITS_PER_UNIT,
PER_UNIT,
CREDITS_PER_MINUTE,
CREDITS_PER_HOUR,
CREDITS_PER_DAY,
UNITS_PER_MINUTE,
UNITS_PER_HOUR,
UNITS_PER_DAY,
}
Properties
CREDITS_PER_UNIT
PER_UNIT
CREDITS_PER_MINUTE
CREDITS_PER_HOUR
CREDITS_PER_DAY
UNITS_PER_MINUTE
UNITS_PER_HOUR
UNITS_PER_DAY
ProductReference
¶
Contains a unique reference to a Product
data class ProductReference(
val id: String,
val category: String,
val provider: String,
)
ProductType
¶
A classifier for a Product
enum class ProductType {
STORAGE,
COMPUTE,
INGRESS,
LICENSE,
NETWORK_IP,
}
For more information, see the individual Product
s:
STORAGE
: SeeProduct.Storage
COMPUTE
: SeeProduct.Compute
INGRESS
: SeeProduct.Ingress
LICENSE
: SeeProduct.License
NETWORK_IP
: SeeProduct.NetworkIP
Properties
STORAGE
See Product.Storage
COMPUTE
See Product.Compute
INGRESS
See Product.Ingress
LICENSE
See Product.License
NETWORK_IP
See Product.NetworkIP
ProductsBrowseRequest
¶
The base type for requesting paginated content.
data class ProductsBrowseRequest(
val itemsPerPage: Int?,
val next: String?,
val consistency: PaginationRequestV2Consistency?,
val itemsToSkip: Long?,
val filterName: String?,
val filterProvider: String?,
val filterArea: ProductType?,
val filterCategory: String?,
val filterVersion: Int?,
val showAllVersions: Boolean?,
val includeBalance: Boolean?,
)
Paginated content can be requested with one of the following consistency
guarantees, this greatly changes the
semantics of the call:
Consistency | Description |
---|---|
PREFER |
Consistency is preferred but not required. An inconsistent snapshot might be returned. |
REQUIRE |
Consistency is required. A request will fail if consistency is no longer guaranteed. |
The consistency
refers to if collecting all the results via the pagination API are consistent. We consider the
results to be consistent if it contains a complete view at some point in time. In practice this means that the results
must contain all the items, in the correct order and without duplicates.
If you use the PREFER
consistency then you may receive in-complete results that might appear out-of-order and can
contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful
for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly
consistent.
The results might become inconsistent if the client either takes too long, or a service instance goes down while
fetching the results. UCloud attempts to keep each next
token alive for at least one minute before invalidating it.
This does not mean that a client must collect all results within a minute but rather that they must fetch the next page
within a minute of the last page. If this is not feasible and consistency is not required then PREFER
should be used.
📝 NOTE: Services are allowed to ignore extra criteria of the request if the next
token is supplied. This is
needed in order to provide a consistent view of the results. Clients should provide the same criterion as they
paginate through the results.
Properties
itemsPerPage
: Int?
Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
Int?
next
: String?
A token requesting the next page of items
String?
consistency
: PaginationRequestV2Consistency?
Controls the consistency guarantees provided by the backend
PaginationRequestV2Consistency?
itemsToSkip
: Long?
Items to skip ahead
Long?
filterName
: String?
String?
filterProvider
: String?
String?
filterArea
: ProductType?
ProductType?
filterCategory
: String?
String?
filterVersion
: Int?
Int?
showAllVersions
: Boolean?
Boolean?
includeBalance
: Boolean?
Boolean?
ProductsRetrieveRequest
¶
data class ProductsRetrieveRequest(
val filterName: String,
val filterCategory: String,
val filterProvider: String,
val filterArea: ProductType?,
val filterVersion: Int?,
val includeBalance: Boolean?,
)
Properties
filterName
: String
String
filterCategory
: String
String
filterProvider
: String
String
filterArea
: ProductType?
ProductType?
filterVersion
: Int?
Int?
includeBalance
: Boolean?
Boolean?