Gracias por tu visita. Esta página solo está disponible en inglés.

Alexa.PercentageController Interface

The Alexa.PercentageController interface describes the messages used to control properties of endpoints that can be expressed as a percentage. Use this interface only if there is not a more specific controller interface that applies to your device. In general, you should implement the most specific interface possible. For example, if you want to handle request specific to brightness values, use Alexa.BrightnessController. If you want to handle requests specific to the power level of an endpoint such as a dimmer switch, see Alexa.PowerLevelController.

For the list of locales that are supported for the PercentageController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.PercentageController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, set the <device name> to thirty percent.
Alexa, increase <device name> by ten percent.
Alexa, decrease <device name> by twenty percent.

Alexa, stelle <Geräteame> auf Anzahl Prozent.
Alexa, erhöhe <Gerätename> um 10 Prozent.
Alexa, reduziere <Gerätename> um 20 Prozent.

deviceのグループを30%に設定して
deviceを15%明るくしてください

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Directives

SetPercentage

Request to set the percentage value for an endpoint.

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "SetPercentage",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentage": 74
    }
  }
}
Field Description Type Required
percentage The percentage value to set for the device. Integer from 0-100, inclusive. Yes

AdjustPercentage

Request to increase or decrease the percentage value of a device setting.

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

Field Description Type Required
percentageDelta The desired change in percentage. A positive or negative integer value used to increase or decrease the percentage. For example, a starting value of 100 and a percentage delta of -3 would result in a final value of 97. Integer from -100 to 100, inclusive. Yes

Properties and Events

For this capability, you must either reply:

  • Synchronously, which means you send a Response event to Alexa from the Lambda function.
  • Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

When you send a Response, you should include the state of the interface properties in the context of the message.

Properties

Property Name Type Description
percentage Percentage The percentage value of an appliance setting. This could be the brightness, speed, power level or other values. The value is an integer ranging from 0 to 100, inclusive.

Response

If a percentage directive was successfully handled, you should respond with an Response event.

Example Response

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.PercentageController",
      "name": "percentage",
      "value": 74,
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

PercentageController

Interface Description
Alexa.BrightnessController Sets brightness for a light as a percentage.