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

Alexa.Media.PlayQueue GetItem

Music skill certification begins in January 2019

You can create, develop, enable, test, and submit music skills for certification now, but the Alexa certification team will begin processing and certifying music skills in January 2019. You will receive feedback about the status of your music skill after certification is complete.

If an item's stream URI has expired, Alexa sends a GetItem request to obtain a new (refreshed) URI to begin playback on an Alexa device. This interface is optional. Implement this interface only if the stream URIs returned by your music service cloud can expire.

The primary use case for this API is when an item cached by Alexa is expired and needs to be refreshed. For example, a user is listening to music on their Alexa device, and then says "Alexa, pause". One hour later, the user says "Alexa, resume" but the stream URI for the item is now expired (based on the item's stream.validUntil field). In this scenario, Alexa calls GetItem to receive a new stream URI, and then sends the new stream URI to the device to resume playback.

If your skill does not expire stream URIs, or if the URI expiration period (stream.validUntil field) is always longer than 24 hours, your skill does not need to support the GetItem API. When a user pauses for an extended period of time (many hours), Alexa eventually forgets about the paused stream. In these cases, when a user later asks "Alexa, resume", Alexa asks the user what she or he would like to hear and then sends new GetPlayableContent and Initiate requests to the skill.

Configure a skill to receive requests

You must configure your music skill to support this API before Alexa will send requests to it. You can do this on the Interfaces page while building your skill in the Alexa Skills Kit developer console, or by adding the API to the interfaces object in your skill manifest JSON if you're using the ASK CLI to build your skill. For an example music skill manifest, see the example music skill manifest.

Request structure

Following is the structure of a GetItem request.

Header

For an overview of the header format, see message header.

Field Value Type
messageId A version 4 UUID string
namespace Alexa.Media.PlayQueue string
name GetItem string
payloadVersion 1.0 string

Payload

The following table describes the fields in the payload of a GetItem request.

Field Description Type
requestContext An object containing context information about the request. See the RequestContext object for more information. object
targetItemReference An object identifying the item to get. See the MediaReference object for more information. object

Example GetItem request

Imagine the following scenario: Alexa is playing the first song from a skill's Initiate response. The user pauses playback, then one hour later says "Alexa, resume". The stream URI is now expired, so Alexa will send a GetItem request to obtain a new, non-expired stream URI. See the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media.PlayQueue",
    "name": "GetItem",
    "payloadVersion": "1.0"
  },
  "payload": {
    "requestContext": {
      "user": {
        "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
        "accessToken": "e72e16c7e42f292c691234567c838347ae178b4a"
      },
      "location": {
        "originatingLocale": "en-US"
      }
    },
    "targetItemReference": {
      "namespace": "Alexa.Audio.PlayQueue",
      "name": "item",
      "value": {
        "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
        "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
        "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
      }
    }
  }
}

Response structure

When the skill locates the requested item, it sends a GetItem.Response.

Header

For an overview of the header format, see message header.

Field Value Required? Type
messageId A version 4 UUID yes string
namespace Alexa.Audio.PlayQueue yes string
name GetItem.Response yes string
payloadVersion 1.0 yes string

Payload

The following table describes the fields in the payload of a GetItem response.

Field Description Required? Type
item The requested item in the play queue. See the Item object for more information. yes object

Example GetItem response

In response to the preceding example request, the skill returns information about the item identified in the request. See the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetItem.Response",
    "payloadVersion": "1.0"
  },
  "payload": {
    "item": {
      "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
      "playbackInfo": {
        "type": "DEFAULT"
      },
      "metadata": {
        "type": "TRACK",
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "Float On"
          },
          "display": "float on"
        },
        "art": {
          "sources": [
            {
              "url": "https://images.example.com/images/cover/album-art.jpg",
              "size": "X_SMALL",
              "widthPixels": 48,
              "heightPixels": 48
            },
            {
              "url": "https://images.example.com/images/cover/album-art.jpg",
              "size": "SMALL",
              "widthPixels": 60,
              "heightPixels": 60
            },
            {
              "url": "https://images.example.com/images/cover/album-art.jpg",
              "size": "MEDIUM",
              "widthPixels": 110,
              "heightPixels": 110
            },
            {
              "url": "https://images.example.com/images/cover/album-art.jpg",
              "size": "LARGE",
              "widthPixels": 256,
              "heightPixels": 256
            },
            {
              "url": "https://images.example.com/images/cover/album-art.jpg",
              "size": "X_LARGE",
              "widthPixels": 600,
              "heightPixels": 600
            }
          ]
        }
      },
      "durationInMilliseconds": 208000,
      "controls": [
        {
          "type": "COMMAND",
          "name": "NEXT",
          "enabled": true
        },
        {
          "type": "COMMAND",
          "name": "PREVIOUS",
          "enabled": false
        }
      ],
      "rules": {
        "feedbackEnabled": true
      },
      "stream": {
        "id": "STREAMID_92_14629004",
        "uri": "https://cdn.example.com/api/1/streaming-file.mp3",
        "offsetInMilliseconds": 0,
        "validUntil": "2018-05-10T19:11:35Z"
      },
      "feedback": {
        "type": "PREFERENCE",
        "value": "POSITIVE"
      }
    }
  }
}

Example ErrorResponse

If the skill cannot find the item identified in the request, it returns a media-specific error response as in the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "ITEM_NOT_FOUND",
    "message": "The item does not exist"
  }
}