Set channel metadata
Sets metadata for the specified channel. Returns the channel object, optionally including custom properties.
Note:
- You can change all of the channel's metadata except its identifier.
- Invalid property names are silently ignored and will not cause a request to fail.
- If you set the
customproperty, you must completely replace it since partial updates are not supported. - The custom object can only contain scalar values.
| Path Parameters |
|---|
sub_key string — REQUIREDYour app's subscribe key from Admin Portal. |
channel string — REQUIREDThe channel ID to perform the operation on. Must not be empty and can contain up to 92 UTF-8 byte sequences. Prohibited characters are: |
| Query Parameters |
|---|
include string[]Possible values: [ List of additional/complex metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata. |
auth stringString which is either the auth key (Access Manager legacy) or a valid token (Access Manager) used to authorize the operation if access control is enabled. Authorization token with permissions to perform the request. |
signature stringSignature used to verify that the request was signed with the secret key associated with the subscribe key. If Access Manager is enabled, either a valid authorization token or a signature are required. Check Access Manager documentation for details on how to compute the signature. |
timestamp integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP.
Required if |
| Header Parameters |
|---|
If-Match stringAn optional HTTP header that prevents concurrent modifications of the same Channel object by allowing clients to (optionally) request that their updates only be performed if the object hasn't been modified since it was read. You can add Imagine the use case where you want to modify an existing Channel object only if it hasn't been modified since the last time you read it. This is how the flow would look like:
Note The |
| Request Body — REQUIRED JSON object with channel metadata to set. |
|---|
name stringPossible values: 1 ≤ length The channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. |
description stringDescription of the channel. Max. 2,048 characters. |
type stringChannel type. Max. 50 characters. |
status stringChannel status. Max. 50 characters. |
custom objectJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported. NOTE: If you set |
| Responses | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200Successfully set the channel metadata.
| |||||||||||
400The request body contains invalid data.
| |||||||||||
403Disabled - The subscribe key doesn't have App Context API enabled. Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.
| |||||||||||
412Conditional operation cannot be performed because the target resource has changed since the last retrieval.
| |||||||||||
415The format of the request body you supplied isn't supported. The request body must be in JSON format.
| |||||||||||
429Request rate limit exceeded.
| |||||||||||
500An internal server error occurred.
| |||||||||||
503Request processing exceeded the maximum allowed time.
|
If-MatchYou can add
If-Match in the Set channel metadata requests and set it to the value of the `eTag` field from a previous **Get channel metadata** response body.Imagine the use case where you want to modify an existing Channel object only if it hasn't been modified since the last time you read it.
This is how the flow would look like:
1. The client reads the details of a Channel object from App Context API through the **Get channel metadata** request that returns a response body containing the
eTag value representing the object's current state, like 8f6da76a321017a34e0a72ed674393ee.1. The client sends the
eTag value of 8f6da76a321017a34e0a72ed674393ee in the If-Match HTTP header in a subsequent Set channel metadata request, like -H 'If-Match: 8f6da76a321017a34e0a72ed674393ee'.1. Since that eTag value in the
If-Match HTTP header matches the Channel object's current eTag value, the Set channel metadata request will succeed.If the request is sent with an old
eTag value that doesn't match the Channel object's current eTag value, the request will fail with a 412 (Precondition failed) error.Note The
If-Match precondition checking for concurrent modifications is currently not supported for the membership/members' metadata APIs. These APIs also return an eTag field in the response body, but that field is not yet checked in the request header.sub_key*channel*Prohibited characters are:
,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.includeauthsignatureIf Access Manager is enabled, either a valid authorization token or a signature are required.
Check Access Manager documentation for details on how to compute the signature.
timestampRequired if
signature parameter is supplied.name"myChannel1"descriptiontypestatuscustomNOTE: If you set
custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers.{
"name": "My channel",
"description": "A channel that is mine."
}statusdata{"id":"myChannel3","name":"My channel","description":"A channel that is mine.","updated":"2019-02-20T23:11:20.893Z","eTag":"RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="}{
"status": 200,
"data": {
"id": "myChannel3",
"name": "My channel",
"description": "A channel that is mine.",
"updated": "2019-02-20T23:11:20.893Z",
"eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
}
}statuserror{
"status": 400,
"error": {
"message": "Request payload contained invalid input.",
"source": "metadata",
"details": [
{
"message": "The email must be a valid email address.",
"location": "uuid.email",
"locationType": "body"
}
]
}
}statuserror{
"status": 403,
"error": {
"message": "Invalid signature",
"source": "authz",
"details": [
{
"message": "Client and server produced different signatures for the same inputs.",
"location": "signature",
"locationType": "query"
}
]
}
}statuserror{
"status": 412,
"error": {
"message": "Resource already changed by another request since the last retrieval.",
"source": "metadata"
}
}statuserror{
"status": 415,
"error": {
"message": "Request payload must be in JSON format.",
"source": "metadata"
}
}statuserror{
"status": 429,
"error": {
"message": "You have exceeded the maximum number of requests per second allowed for your subscribe key.",
"source": "metadata"
}
}statuserror{
"status": 500,
"error": {
"message": "An unexpected error occurred while processing the request.",
"source": "metadata"
}
}statuserror{
"status": 503,
"error": {
"message": "The server took longer to respond than the maximum allowed processing time.",
"source": "metadata"
}
}