Tutorial: Criar um pipeline que implanta uma skill do Amazon Alexa

Nesse tutorial, você configura um pipeline que fornece continuamente sua skill da Alexa usando o Alexa Skills Kit como o provedor de implantação em seu estágio de implantação. O pipeline concluído detecta alterações em sua skill quando você faz uma alteração nos arquivos de origem em seu repositório de origem. O pipeline usa o Alexa Skills Kit para implantar no estágio de desenvolvimento de skills da Alexa.

nota

Este atributo não está disponível na região Ásia-Pacífico (Hong Kong) ou Europa (Milão). Para usar outras ações de implantação disponíveis nessa região, consulte Implantar integrações de ações.

Para criar a skill personalizada como uma função do Lambda, consulte Hospedar uma skill personalizada como uma função do AWS Lambda. Também é possível criar um pipeline que use arquivos de origem do Lambda e um projeto do CodeBuild para implantar alterações no Lambda para a skill. Por exemplo, para criar uma nova skill e uma função Lambda relacionada, você pode criar um projeto do AWS CodeStar. Consulte Criar um projeto de skill da Alexa no AWS CodeStar Para essa opção, o pipeline inclui um terceiro estágio de compilação com uma ação do CodeBuild e uma ação no estágio de implantação para o AWS CloudFormation.

Pré-requisitos

Você já deve ter o seguinte:

• Um repositório do CodeCommit. Você pode usar o repositório do AWS CodeCommit que você criou em Tutorial: Criar um pipeline simples (repositório do CodeCommit).

• Uma conta de desenvolvedor da Amazon. Essa é a conta que possui suas skills na Alexa. Você pode criar uma conta gratuitamente no Alexa Skills Kit.

• Uma skill da Alexa. Você pode criar um exemplo de skill usando o tutorial Obter código de exemplo da skill personalizada.

• Instale a CLI do ASK e configure-a usando ask init com as credenciais da AWS. Consulte Instalar e inicializar a CLI do ASK.

Etapa 1: Criar um perfil de segurança do LWA dos serviços de desenvolvedor da Alexa

Nessa seção, crie um perfil de segurança para usar com o Login with Amazon (LWA). Se você já tiver um perfil, ignore esta etapa.

• Use as etapas em generate-lwa-tokens para criar um perfil de segurança.

• Depois de criar o perfil, anote o Client ID (ID do cliente) e o Client Secret (Segredo do cliente).

• Certifique-se de inserir os Allowed Return URLs (URLs de devolução permitidos), conforme fornecido nas instruções. Os URLs permitem que o comando da CLI do ASK redirecione as solicitações de token de atualização.

Etapa 2: Criar arquivos de origem de skill da Alexa e enviar ao repositório do CodeCommit

Nessa seção, você cria e envia seus arquivos de origem de skills da Alexa para o repositório que o pipeline usa para o estágio de origem. Para a skill que você criou no console do desenvolvedor da Amazon, você produz e envia o seguinte:

• Um arquivo skill.json.

• Uma pasta interactionModel/custom.

  nota

  Essa estrutura de diretório está em conformidade com os requisitos de formato do pacote de skills do Alexa Skills Kit, conforme descrito em Formato do pacote de skills. Se a estrutura do diretório não usar o formato correto do pacote de skills, as alterações não serão implantadas com êxito no console do Alexa Skills Kit.

Como criar arquivos de origem para sua skill

1. Recupere o ID da skill do console do desenvolvedor do Alexa Skills Kit. Use este comando:

   ask api list-skills

   Localize a skill por nome e copie o ID associado no campo skillId.

2. Gere um arquivo skill.json que contém os detalhes da skill. Use este comando:

   ask api get-skill -s skill-ID > skill.json

3. (Opcional) Crie uma pasta interactionModel/custom.

   Use esse comando para gerar o arquivo de modelo de interação dentro da pasta. Para localidade, esse tutorial usa en-US como a localidade no nome do arquivo.

   ask api get-model --skill-id skill-ID --locale locale >
       ./interactionModel/custom/locale.json

Como enviar arquivos ao repositório do CodeCommit

1. Envie ou faça upload dos arquivos ao repositório do CodeCommit. Esses arquivos são o artefato de origem gerado pelo assistente Create Pipeline (Criar pipeline) para a ação de implantação no AWS CodePipeline. Os arquivos devem ter a seguinte aparência em seu diretório local:

   skill.json
   /interactionModel
     /custom
       |en-US.json

2. Selecione o método que deseja utilizar para carregar seus arquivos:

   1. Para usar a linha de comando Git a partir de um repositório clonado no computador local:

      1. Execute o seguinte comando para organizar todos os seus arquivos de uma só vez:

         git add -A

      2. Execute o seguinte comando para confirmar os arquivos com uma mensagem de confirmação:

         git commit -m "Added Alexa skill files"

      3. Execute o seguinte comando para enviar os arquivos do repositório local ao repositório do CodeCommit:

         git push

   2. Para usar o console do CodeCommit para fazer upload dos arquivos:

      1. Abra o console do CodeCommit e selecione o repositório na lista Repositórios.

      2. Selecione Add file (Adicionar arquivo) e clique em Upload file (Carregar arquivo).

      3. Clique em Choose file (Selecionar arquivo) e localize o arquivo. Informe seu nome de usuário e endereço de e-mail para confirmar a alteração. Escolha Commit changes (Confirmar alterações).

      4. Repita essa etapa para cada arquivo que deseja carregar.

Etapa 3: Usar os comandos da CLI do ASK para criar um token de atualização

O CodePipeline usa um token de atualização com base no ID do cliente e no segredo na conta de desenvolvedor da Amazon para autorizar as ações que ele realiza em seu nome. Nessa seção, você usa a CLI do ASK para criar o token. Você pode usar essas credenciais quando usar o assistente Create Pipeline (Criar pipeline).

Para criar um token de atualização com as credenciais da conta de desenvolvedor da Amazon

1. Use o seguinte comando:

   ask util generate-lwa-tokens

2. Quando solicitado, insira o ID de cliente e o segredo, conforme mostrado neste exemplo:

   ? Please type in the client ID: 
   amzn1.application-client.example112233445566
   ? Please type in the client secret:
   example112233445566

3. A página de login do navegador será exibida. Faça login com as credenciais da conta de desenvolvedor da Amazon.

4. Volte para a tela de linha de comando. O token de acesso e o token de atualização serão gerados na saída. Copie o token de atualização retornado na saída.

Etapa 4: Criar o pipeline

Nesta seção, você criará um pipeline com as seguintes ações:

• Um estágio de origem com uma ação do CodeCommit em que os artefatos de origem são os arquivos de skill da Alexa que são compatíveis com a skill.

• Um estágio de implantação com uma ação de implantação do Alexa Skills Kit.

Criar um pipeline com o assistente

1. Faça login no AWS Management Console e abra o console do CodePipeline em http://console.aws.amazon.com/codesuite/codepipeline/home.

2. Escolha a região da AWS onde você deseja criar o projeto e seus recursos. O tempo de execução da skill da Alexa está disponível somente nas seguintes regiões:

   • Ásia-Pacífico (Tóquio)

   • Europa (Irlanda)

   • Leste dos EUA (Norte da Virgínia)

   • Oeste dos EUA (Oregon)

3. Na página Welcome (Bem-vindo), Getting started (Conceitos básicos) ou Pipelines, selecione Create pipeline (Criar pipeline).

4. Em Step 1: Choose pipeline settings (Etapa 1: selecionar as configurações do pipeline), em Pipeline name (Nome do pipeline), insira MyAlexaPipeline.

5. Em Tipo de pipeline, selecione V1 para os fins deste tutorial. Também é possível selecionar V2; no entanto, observe que os tipos de pipeline diferem em características e preços. Para obter mais informações, consulte Tipos de Pipeline.

6. Em Perfil de serviço, selecione Novo perfil de serviço para permitir que o CodePipeline crie um perfil de serviço no IAM.

7. Deixe as configurações em Advanced settings (Configurações avançadas) como padrão e escolha Next (Próximo).

8. Em Step 2: Add source stage (Etapa 2: Adicionar estágio de origem), em Source provider (Fornecedor de origem), escolha AWS CodeCommit. Em Nome do repositório, selecione o nome do repositório do CodeCommit criado em Etapa 1: criar um repositório do CodeCommit. Em Nome do ramo, selecione o nome do ramo que contém a última atualização do código.

   Assim que selecionar o nome do repositório e a ramificação, uma mensagem exibe a regra do Amazon CloudWatch Events a ser criada para esse pipeline.

   Escolha Next (Próximo).

9. Em Step 3: Add build stage (Etapa 3: Adicionar estágio de construção), selecione Skip build stage (Pular estágio de compilação) e aceite a mensagem de aviso ao clicar novamente em Skip (Pular).

   Escolha Next (Próximo).

10. Em Step 4: Add deploy stage (Etapa 4: Adicionar estágio de implantação):

    1. Em Deploy provider (Provedor de implantação), escolha Alexa Skills Kit.

    2. Em Alexa skill ID (ID da skill da Alexa), insira o ID da skill atribuído à sua skill no console do desenvolvedor do Alexa Skills Kit.

    3. Em Client ID (ID do cliente), insira o ID do aplicativo que você registrou.

    4. Em Client secret (Segredo do cliente), insira o segredo que você escolheu quando se registrou.

    5. Em Refresh token (Token de atualização), insira o token que você gerou na etapa 3.

       

    6. Escolha Next (Próximo).

11. Em Etapa 5: Revisar, revise as informações e, então selecione Criar pipeline.

Etapa 5: Realizar uma alteração em qualquer arquivo de origem e verificar a implantação

Inclua uma alteração em sua skill e envie-a ao repositório. Deste modo, a execução de seu pipeline é acionada. Verifique se sua skill está atualizada no console do desenvolvedor do Alexa Skills Kit.