As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Desenvolver componentes do AWS IoT Greengrass
Você pode desenvolver e testar componentes em seu dispositivo principal do Greengrass. Como resultado, você pode criar e iterar seu software do AWS IoT Greengrass sem interagir com a Nuvem AWS. Ao concluir uma versão do seu componente, você pode carregá-la na nuvem do AWS IoT Greengrass, para que você e sua equipe possam implantar o componente em outros dispositivos da frota. Para obter mais informações sobre como implantar componentes, consulte [Implemente AWS IoT Greengrass componentes em dispositivos](manage-deployments.md).
Cada componente é composto por uma *fórmula* e *artefatos*.
+ **Fórmulas**
Cada componente contém um arquivo de fórmula, que define os metadados dele. A fórmula também especifica os parâmetros de configuração, dependências do componente, o ciclo de vida e a compatibilidade da plataforma. O ciclo de vida do componente define os comandos que instalam, executam e desligam o componente. Para obter mais informações, consulte [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md).
Você pode definir fórmulas no formato [JSON](https://en.wikipedia.org/wiki/JSON) ou [YAML](https://en.wikipedia.org/wiki/YAML).
+ **Artefatos**
Os componentes podem ter qualquer número de artefatos, que são binários de componentes. Os artefatos podem incluir scripts, código compilado, recursos estáticos e quaisquer outros arquivos que um componente consuma. Os componentes também podem consumir artefatos das dependências deles.
O AWS IoT Greengrass fornece componentes pré-criados que você pode usar em suas aplicações e implantar em seus dispositivos. Por exemplo, você pode usar o componente do gerenciador de fluxos para carregar dados para vários serviços da AWS, ou usar o componente de métricas do CloudWatch para publicar métricas personalizadas no Amazon CloudWatch. Para obter mais informações, consulte [Componentes fornecidos pela AWS](public-components.md).
O AWS IoT Greengrass organiza um índice dos componentes do Greengrass, chamado Catálogo de Software do Greengrass. Este catálogo rastreia os componentes do Greengrass que são desenvolvidos pela comunidade do Greengrass. A partir desse catálogo, você pode baixar, modificar e implantar componentes para criar suas aplicações Greengrass. Para obter mais informações, consulte [Componentes da comunidade](greengrass-software-catalog.md).
O software AWS IoT Greengrass Core executa componentes como usuário e grupo do sistema, como `ggc_user` e `ggc_group`, que você configura no dispositivo principal. Isso significa que os componentes têm as permissões desse usuário do sistema. Se você usar um usuário do sistema sem um diretório inicial, os componentes não poderão usar comandos de execução ou códigos que usem um diretório inicial. Isso significa que você não pode usar o comando `pip install some-library --user` para instalar pacotes Python, por exemplo. Se você seguiu o [tutorial de introdução](getting-started.md) para configurar seu dispositivo principal, o usuário do sistema não tem um diretório inicial. Para obter mais informações sobre como configurar o usuário e o grupo que executam os componentes, consulte [Configurar o usuário que executa os componentes](configure-greengrass-core-v2.md#configure-component-user).
**nota**
O AWS IoT Greengrass usa versões semânticas para componentes. As versões semânticas seguem um sistema de numeração *principal*.*secundária*.*patch*. Por exemplo, a versão `1.0.0` representa a primeira versão principal de um componente. Para mais informações, consulte a [especificação de versão semântica](https://semver.org/).
**Topics**
+ [Ciclo de vida do componente](#component-lifecycle)
+ [Tipos de componentes](#component-types)
+ [Criar componentes do AWS IoT Greengrass](create-components.md)
+ [Testar os componentes do AWS IoT Greengrass com implantações locais](test-components.md)
+ [Publish components to deploy to your core devices](publish-components.md)
+ [Interaja com AWS os serviços](interact-with-aws-services.md)
+ [Executar um contêiner do Docker](run-docker-container.md)
+ [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md)
+ [Referência de variável de ambiente do componente](component-environment-variables.md)
## Ciclo de vida do componente
O *ciclo de vida do componente* define os estágios que o software AWS IoT Greengrass Core usa para instalar e executar componentes. Cada estágio define um script e outras informações que especificam como o componente se comporta. Por exemplo, quando você instala um componente, o software AWS IoT Greengrass Core executa o script de ciclo de vida `install` desse componente. Os componentes nos dispositivos principais têm os seguintes estados de ciclo de vida:
+ `NEW`: a fórmula e os artefatos do componente são carregados no dispositivo principal, mas o componente não está instalado. Depois que um componente entra nesse estado, ele executa o [script de instalação](component-recipe-reference.md#install-lifecycle-definition).
+ `INSTALLED`: o componente está instalado no dispositivo principal. O componente entra nesse estado depois de executar o [script de instalação](component-recipe-reference.md#install-lifecycle-definition).
+ `STARTING`: o componente está iniciando no dispositivo principal. O componente entra nesse estado quando executa o [script de startup](component-recipe-reference.md#startup-lifecycle-definition). Se a inicialização for bem-sucedida, o componente entrará no estado `RUNNING`.
+ `RUNNING`: o componente está sendo executado no dispositivo principal. O componente entra nesse estado quando executa o [script de execução](component-recipe-reference.md#run-lifecycle-definition) ou quando tem processos ativos em segundo plano a partir do script de startup.
+ `FINISHED`: o componente foi executado com sucesso e concluiu a execução.
+ `STOPPING`: o componente está parando. O componente entra nesse estado quando executa o [script de encerramento](component-recipe-reference.md#shutdown-lifecycle-definition).
+ `ERRORED`: o componente encontrou um erro. Quando o componente entra nesse estado, ele executa o [script de recuperação](component-recipe-reference.md#recover-lifecycle-definition). Em seguida, o componente é reiniciado para tentar retornar ao uso normal. Se o componente entrar no estado `ERRORED` três vezes sem uma execução bem-sucedida, o componente se tornará `BROKEN`.
+ `BROKEN`: o componente encontrou erros várias vezes e não conseguiu se recuperar. Você deve implantar o componente novamente para corrigi-lo.
## Tipos de componentes
O *tipo de componente* especifica como o software AWS IoT Greengrass Core executa um componente. Os componentes podem ter os tipos a seguir:
+ **Núcleo** (`aws.greengrass.nucleus`)
O núcleo do Greengrass é o componente que fornece a funcionalidade mínima do software AWS IoT Greengrass Core. Para obter mais informações, consulte [Greengrass nucleus](greengrass-nucleus-component.md).
+ **Plug-in** (`aws.greengrass.plugin`)
O núcleo do Greengrass executa um componente de plug-in na mesma Máquina Virtual Java (JVM) que o núcleo. O núcleo é reiniciado quando você altera a versão de um componente de plug-in em um dispositivo principal. Para instalar e executar componentes do plug-in, configure o núcleo do Greengrass para ser executado como um serviço do sistema. Para obter mais informações, consulte [Configurar o Greengrass nucleus como um serviço do sistema](configure-greengrass-core-v2.md#configure-system-service).
Vários componentes fornecidos pela AWS são componentes de plug-ins, o que permite que eles interajam diretamente com o núcleo do Greengrass. Esse plug-in usa o mesmo arquivo de log do núcleo do Greengrass. Para obter mais informações, consulte [Monitore AWS IoT Greengrass logs](monitor-logs.md).
+ **Genérico** (`aws.greengrass.generic`)
O núcleo do Greengrass executa os scripts de ciclo de vida de um componente genérico, se ele definir um ciclo de vida.
Esse é o tipo padrão para componentes personalizados.
+ **Lambda** (`aws.greengrass.lambda`)
O núcleo do Greengrass executa um componente de função do Lambda usando o [componente inicializador do Lambda](lambda-launcher-component.md).
Quando você cria um componente a partir de uma função do Lambda, o componente tem esse tipo. Para obter mais informações, consulte [Executar funções AWS Lambda.](run-lambda-functions.md).
**nota**
Não recomendamos especificar o tipo de componente em uma fórmula. O AWS IoT Greengrass define o tipo para você ao criar um componente.
# Criar componentes do AWS IoT Greengrass
Você pode desenvolver componentes personalizados do AWS IoT Greengrass em um computador de desenvolvimento local ou em um dispositivo principal do Greengrass. O AWS IoT Greengrass fornece a [interface de linha de comando do kit de desenvolvimento do AWS IoT Greengrass (GDK CLI)](greengrass-development-kit-cli.md) para criar e publicar componentes a partir de modelos predefinidos e [componentes da comunidade](greengrass-software-catalog.md). Você também pode executar comandos de shell integrados para criar e publicar componentes. Escolha entre as opções a seguir para criar componentes personalizados do Greengrass:
+ **Usar a CLI do kit de desenvolvimento do Greengrass**
Use a CLI do GDK para desenvolver componentes em um computador de desenvolvimento local. A CLI do GDK cria e empacota o código-fonte do componente em uma fórmula e artefatos que você pode publicar como um componente privado no serviço do AWS IoT Greengrass. É possível configurar a CLI do GDK para atualizar automaticamente a versão do componente e os URIs do artefato ao publicar o componente, assim não é preciso atualizar a fórmula toda vez. Para desenvolver um componente usando a CLI do GDK, você pode começar com um modelo ou componente da comunidade do [Catálogo de Software do Greengrass](greengrass-software-catalog.md). Para obter mais informações, consulte [Interface de linha de comando do kit de desenvolvimento do AWS IoT Greengrass](greengrass-development-kit-cli.md).
+ **Executar comandos de shell integrados**
É possível executar comandos shell integrados para desenvolver componentes em um computador de desenvolvimento local ou em um dispositivo principal do Greengrass. Você usa comandos shell para copiar ou criar o código-fonte do componente em artefatos. Cada vez que você cria uma nova versão de um componente, você deve criar ou atualizar a fórmula com a nova versão do componente. Ao publicar o componente no serviço do AWS IoT Greengrass, você deve atualizar o URI para cada artefato do componente na fórmula.
**Topics**
+ [Criar um componente (CLI do GDK)](#create-component-gdk-cli)
+ [Criar um componente (comandos shell)](#create-component-shell-commands)
## Criar um componente (CLI do GDK)
Siga as instruções nesta seção para criar e montar um componente usando a CLI do GDK.
**Para desenvolver um componente do Greengrass (CLI do GDK)**
1. Se você ainda não tiver feito isso, instale a CLI do GDK no computador de desenvolvimento. Para obter mais informações, consulte [Instale ou atualize a interface de linha de comando do kit de AWS IoT Greengrass desenvolvimento](install-greengrass-development-kit-cli.md).
1. Mude para a pasta em que você deseja criar pastas de componentes.
------
#### [ Linux or Unix ]
```
mkdir ~/greengrassv2
cd ~/greengrassv2
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir %USERPROFILE%\greengrassv2
cd %USERPROFILE%\greengrassv2
```
------
#### [ PowerShell ]
```
mkdir ~/greengrassv2
cd ~/greengrassv2
```
------
1. Escolha um modelo de componente ou componente da comunidade para baixar. A CLI do GDK baixa o modelo ou o componente da comunidade, para que você possa começar com um exemplo funcional. Use o comando [component list](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-list) para recuperar a lista de modelos ou componentes da comunidade disponíveis.
+ Para listar modelos de componentes, execute o seguinte comando. Cada linha na resposta inclui o nome do modelo e a linguagem de programação.
```
gdk component list --template
```
+ Para listar os componentes da comunidade, execute o seguinte comando.
```
gdk component list --repository
```
1. Crie e altere para uma pasta de componentes na qual a CLI do GDK baixa o modelo ou o componente da comunidade. Substitua *HelloWorld* pelo nome do componente ou por outro nome que ajude a identificar essa pasta de componentes.
------
#### [ Linux or Unix ]
```
mkdir HelloWorld
cd HelloWorld
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir HelloWorld
cd HelloWorld
```
------
#### [ PowerShell ]
```
mkdir HelloWorld
cd HelloWorld
```
------
1. Baixe o modelo ou componente da comunidade para a pasta atual. Use o comando [component init](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init).
+ Para criar uma pasta de componentes a partir de um modelo, execute o comando a seguir. Substitua *HelloWorld* pelo nome do modelo e substitua *python* pelo nome da linguagem de programação.
```
gdk component init --template HelloWorld --language python
```
+ Para criar uma pasta de componentes a partir de um componente da comunidade, execute o seguinte comando. Substitua *ComponentName* pelo nome do componente da comunidade.
```
gdk component init --repository ComponentName
```
**nota**
Se você usa a CLI do GDK v1.0.0, deve executar esse comando em uma pasta vazia. A CLI do GDK baixa o modelo ou componente da comunidade para a pasta atual.
Se você usa a CLI do GDK v1.1.0 ou posterior, pode especificar o argumento `--name` para especificar a pasta em que a CLI do GDK baixa o modelo ou o componente da comunidade. Se você usar esse argumento, especifique uma pasta que não existe. A CLI do GDK cria a pasta para você. Se você não especificar esse argumento, a CLI do GDK usa a pasta atual, que deve estar vazia.
1. A CLI do GDK lê o [arquivo de configuração da CLI do GDK](gdk-cli-configuration-file.md), chamado `gdk-config.json`, para criar e publicar componentes. Esse arquivo de configuração existe na raiz da pasta do componente. A etapa anterior cria esse arquivo para você. Nesta etapa, você atualiza `gdk-config.json` com informações sobre o componente. Faça o seguinte:
1. Abra `gdk-config.json` em um editor de texto.
1. (Opcional) Altere o nome do componente. O nome do componente é a chave no objeto `component`.
1. Altere o autor do componente.
1. (Opcional) Altere a versão do componente. Especifique um dos seguintes:
+ `NEXT_PATCH`: quando você escolhe essa opção, a CLI do GDK define a versão quando você publica o componente. A CLI do GDK consulta o serviço do AWS IoT Greengrass para identificar a versão mais recente publicada do componente. Em seguida, ela define a versão para a próxima versão de patch após essa versão. Se você não publicou o componente antes, a CLI do GDK usa a versão `1.0.0`.
Se você escolher essa opção, não poderá usar a [CLI do Greengrass](greengrass-cli-component.md) para implantar e testar localmente o componente em seu computador de desenvolvimento local que executa o software AWS IoT Greengrass Core. Para habilitar implantações locais, você deve especificar uma versão semântica em vez disso.
+ Uma versão semântica, como **1.0.0**. As versões semânticas usam um sistema de numeração *principal*.*secundário*.*patch*. Para mais informações, consulte a [especificação de versão semântica](https://semver.org/).
Se você desenvolver componentes em um dispositivo principal do Greengrass para implantar e testar o componente, escolha essa opção. Você deve criar o componente com uma versão específica para criar implantações locais com a [CLI do Greengrass](greengrass-cli-component.md).
1. (Opcional) Altere a configuração de compilação do componente. A configuração de compilação define como a CLI do GDK transforma a fonte do componente em artefatos. Escolha entre as seguintes opções para `build_system`:
+ `zip`: empacota a pasta do componente em um arquivo ZIP para definir como o único artefato do componente. Escolha essa opção para os seguintes tipos de componentes:
+ Componentes que usam linguagens de programação interpretadas, como Python ou JavaScript.
+ Componentes que empacotam arquivos que não sejam código, como modelos de machine learning ou outros recursos.
A CLI do GDK compacta a pasta do componente em um arquivo zip com o mesmo nome da pasta do componente. Por exemplo, se o nome da pasta do componente for `HelloWorld`, a CLI do GDK cria um arquivo zip chamado `HelloWorld.zip`.
**nota**
Se você usa a CLI do GDK versão 1.0.0 em um dispositivo Windows, a pasta do componente e os nomes dos arquivos zip devem conter somente letras minúsculas.
Quando a CLI do GDK compacta a pasta do componente em um arquivo zip, ela ignora os seguintes arquivos:
+ O arquivo `gdk-config.json`
+ O arquivo da fórmula (`recipe.json` ou `recipe.yaml`)
+ Crie pastas, como `greengrass-build`
+ `maven`: executa o comando `mvn clean package` para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o [Maven](https://maven.apache.org/), como componentes Java.
Em dispositivos Windows, esse recurso está disponível para a CLI do GDK v1.1.0 e versões posteriores.
+ `gradle`: executa o comando `gradle build` para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o [Gradle.](https://gradle.org/) Este atributo está disponível para a CLI do GDK v1.1.0 e posteriores.
O sistema de compilação do `gradle` é compatível com o Kotlin DSL como arquivo de compilação. Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.
+ `gradlew`: executa o comando `gradlew` para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o [Wrapper Gradle](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.
+ `custom`: executa um comando personalizado para transformar a fonte do componente em uma fórmula e artefatos. Especifique o comando personalizado no parâmetro `custom_build_command`.
1. Se você especificar `custom` para`build_system`, adicione o `custom_build_command` ao objeto `build`. Em `custom_build_command`, especifique uma única string ou lista de strings, em que cada string é uma palavra no comando. Por exemplo, para executar um comando de compilação personalizado para um componente C\$1\$1, especifique **["cmake", "--build", "build", "--config", "Release"]**.
1. Se você usar a CLI do GDK v1.1.0 ou posterior, poderá especificar o argumento `--bucket` para especificar o bucket do S3 em que a CLI do GDK carrega os artefatos do componente. Se você não especificar esse argumento, a CLI do GDK será carregada no bucket do S3 cujo nome é `bucket-region-accountId`, em que *bucket* e *região* são os valores que você especifica em `gdk-config.json`, e *accountId* é seu ID da Conta da AWS. A CLI do GDK criará o bucket, se ele não existir.
Altere a configuração de publicação do componente. Faça o seguinte:
1. Especifique o nome do bucket do S3 a ser usado para hospedar os artefatos do componente.
1. Especifique a Região da AWS em que a CLI do GDK publica o componente.
Quando você terminar com esta etapa, o arquivo `gdk-config.json` pode parecer com o exemplo a seguir.
```
{
"component": {
"com.example.PythonHelloWorld": {
"author": "Amazon",
"version": "NEXT_PATCH",
"build": {
"build_system" : "zip"
},
"publish": {
"bucket": "greengrass-component-artifacts",
"region": "us-west-2"
}
}
},
"gdk_version": "1.0.0"
}
```
1. Atualize o arquivo de fórmula do componente, chamado `recipe.yaml` ou `recipe.json`. Faça o seguinte:
1. Se você baixou um modelo ou componente da comunidade que usa o sistema de compilação `zip`, verifique se o nome do artefato zip corresponde ao nome da pasta do componente. A CLI do GDK compacta a pasta do componente em um arquivo zip com o mesmo nome da pasta do componente. A fórmula contém o nome do artefato zip na lista de artefatos do componente e nos scripts de ciclo de vida que usam arquivos no artefato zip. Atualize as definições `Artifacts` e `Lifecycle` de modo que o nome do arquivo zip corresponda ao nome da pasta do componente. Os exemplos de fórmulas parciais a seguir destacam o nome do arquivo zip nas definições `Artifacts` e `Lifecycle`.
------
#### [ JSON ]
```
{
...
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
...
Manifests:
- Platform:
os: all
Artifacts:
- URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
Unarchive: ZIP
Lifecycle:
Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
```
------
1. (Opcional) Atualize a descrição do componente, a configuração padrão, os artefatos, os scripts de ciclo de vida e o suporte à plataforma. Para obter mais informações, consulte [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md).
Ao concluir esta etapa, o arquivo de fórmula pode ser semelhante aos exemplos a seguir.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "{COMPONENT_NAME}",
"ComponentVersion": "{COMPONENT_VERSION}",
"ComponentDescription": "This is a simple Hello World component written in Python.",
"ComponentPublisher": "{COMPONENT_AUTHOR}",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "World"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: "2020-01-25"
ComponentName: "{COMPONENT_NAME}"
ComponentVersion: "{COMPONENT_VERSION}"
ComponentDescription: "This is a simple Hello World component written in Python."
ComponentPublisher: "{COMPONENT_AUTHOR}"
ComponentConfiguration:
DefaultConfiguration:
Message: "World"
Manifests:
- Platform:
os: all
Artifacts:
- URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
Unarchive: ZIP
Lifecycle:
Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
```
------
1. Crie e implante o componente do Greengrass. O comando de [construção do componente](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build) produz uma fórmula e artefatos na pasta `greengrass-build` do componente. Execute o comando a seguir.
```
gdk component build
```
Quando estiver pronto para testar seu componente, use a CLI do GDK para publicá-lo no serviço do AWS IoT Greengrass. Em seguida, você pode implantar o componente nos dispositivos principais do Greengrass. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md).
## Criar um componente (comandos shell)
Siga as instruções nesta seção para criar pastas de fórmulas e artefatos que contêm código-fonte e artefatos para vários componentes.
**Para desenvolver um componente do Greengrass (comandos shell)**
1. Crie uma pasta para seus componentes com subpastas para fórmulas e artefatos. Execute os comandos a seguir em seu dispositivo principal do Greengrass para criar essas pastas e mudar para a pasta do componente. Substitua *\$1/greengrassv2* ou *%USERPROFILE%\$1 greengrassv2* pelo caminho para a pasta a ser usada no desenvolvimento local.
------
#### [ Linux or Unix ]
```
mkdir -p ~/greengrassv2/{recipes,artifacts}
cd ~/greengrassv2
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir %USERPROFILE%\greengrassv2\\recipes, %USERPROFILE%\greengrassv2\\artifacts
cd %USERPROFILE%\greengrassv2
```
------
#### [ PowerShell ]
```
mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts
cd ~/greengrassv2
```
------
1. Use um editor de texto para criar um arquivo de fórmula que defina os metadados, parâmetros, dependências, o ciclo de vida e a capacidade de plataforma do componente. Inclua a versão do componente no nome do arquivo da fórmula para que você possa identificar qual fórmula reflete qual versão do componente. Você pode escolher o formato YAML ou JSON para sua fórmula.
Por exemplo, em um sistema baseado em Linux, você pode executar o comando a seguir para usar o GNU nano para criar o arquivo.
------
#### [ JSON ]
```
nano recipes/com.example.HelloWorld-1.0.0.json
```
------
#### [ YAML ]
```
nano recipes/com.example.HelloWorld-1.0.0.yaml
```
------
**nota**
O AWS IoT Greengrass usa versões semânticas para componentes. As versões semânticas seguem um sistema de numeração *principal*.*secundária*.*patch*. Por exemplo, a versão `1.0.0` representa a primeira versão principal de um componente. Para mais informações, consulte a [especificação de versão semântica](https://semver.org/).
1. Defina a fórmula do seu componente. Para obter mais informações, consulte [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md).
Sua fórmula pode ser semelhante à fórmula de exemplo seguinte do Hello World.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
```
------
Esta fórmula executa uma versão de script do Hello World em Python, que pode ser semelhante ao script de exemplo a seguir.
```
import sys
message = "Hello, %s!" % sys.argv[1]
# Print the message to stdout, which Greengrass saves in a log file.
print(message)
```
1. Crie uma pasta para a versão do componente ser desenvolvida. Recomendamos que você use uma pasta separada para os artefatos de cada versão do componente para poder identificar quais são de cada versão do componente. Execute o comando a seguir.
------
#### [ Linux or Unix ]
```
mkdir -p artifacts/com.example.HelloWorld/1.0.0
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir artifacts/com.example.HelloWorld/1.0.0
```
------
#### [ PowerShell ]
```
mkdir artifacts/com.example.HelloWorld/1.0.0
```
------
**Importante**
Você deve usar o formato a seguir para o caminho da pasta de artefatos. Inclua o nome e a versão do componente que você especificar na fórmula.
```
artifacts/componentName/componentVersion/
```
1. Crie os artefatos do componente na pasta que você criou na etapa anterior. Os artefatos podem incluir software, imagens e quaisquer outros binários que seu componente usa.
Quando seu componente estiver pronto, [teste seu componente](test-components.md).
# Testar os componentes do AWS IoT Greengrass com implantações locais
Se você desenvolver um componente do Greengrass em um dispositivo principal, poderá criar uma implantação local para instalá-lo e testá-lo. Siga as etapas nesta seção para criar uma implantação local.
Se você desenvolver o componente em outro computador, como um de desenvolvimento local, não poderá criar uma implantação local. Em vez disso, publique o componente no serviço AWS IoT Greengrass para que você possa implantá-lo nos dispositivos principais do Greengrass para testá-lo. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md) e [Implemente AWS IoT Greengrass componentes em dispositivos](manage-deployments.md).
**Para testar um componente em um dispositivo principal do Greengrass**
1. O dispositivo principal registra os eventos em log, como atualizações de componentes. Você pode visualizar esse arquivo de log para descobrir e solucionar erros em seu componente, como uma fórmula inválida. Esse arquivo de log também exibe as mensagens que o componente imprime na saída padrão (stdout). Recomendamos que você abra uma sessão de terminal adicional em seu dispositivo principal para observar novas mensagens de log em tempo real. Abra uma nova sessão de terminal, por exemplo, por meio de SSH, e execute o comando a seguir para visualizar os logs. Substitua `/greengrass/v2` pelo caminho para a pasta raiz do AWS IoT Greengrass.
------
#### [ Linux or Unix ]
```
sudo tail -f /greengrass/v2/logs/greengrass.log
```
------
#### [ PowerShell ]
```
gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
```
------
Você também pode visualizar o arquivo de log do seu componente.
------
#### [ Linux or Unix ]
```
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
```
------
#### [ PowerShell ]
```
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
```
------
1. Na sessão de terminal original, execute o comando a seguir para atualizar o dispositivo principal com seu componente. Substitua `/greengrass/v2` pelo caminho para a pasta raiz do AWS IoT Greengrass e substitua *\$1/greengrassv2* pelo caminho para sua pasta de desenvolvimento local.
------
#### [ Linux or Unix ]
```
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--recipeDir ~/greengrassv2/recipes \
--artifactDir ~/greengrassv2/artifacts \
--merge "com.example.HelloWorld=1.0.0"
```
------
#### [ Windows Command Prompt (CMD) ]
```
C:\greengrass\v2\bin\greengrass-cli deployment create ^
--recipeDir %USERPROFILE%\greengrassv2\recipes ^
--artifactDir %USERPROFILE%\greengrassv2\artifacts ^
--merge "com.example.HelloWorld=1.0.0"
```
------
#### [ PowerShell ]
```
C:\greengrass\v2\bin\greengrass-cli deployment create `
--recipeDir ~/greengrassv2/recipes `
--artifactDir ~/greengrassv2/artifacts `
--merge "com.example.HelloWorld=1.0.0"
```
------
**nota**
Você também pode usar o comando `greengrass-cli deployment create` para definir o valor dos parâmetros de configuração do seu componente. Para obter mais informações, consulte [criar](gg-cli-deployment.md#deployment-create).
1. Use o comando `greengrass-cli deployment status` para monitorar o andamento da implantação do componente.
------
#### [ Unix or Linux ]
```
sudo /greengrass/v2/bin/greengrass-cli deployment status \
-i deployment-id
```
------
#### [ Windows Command Prompt (CMD) ]
```
C:\greengrass\v2\bin\greengrass-cli deployment status ^
-i deployment-id
```
------
#### [ PowerShell ]
```
C:\greengrass\v2\bin\greengrass-cli deployment status `
-i deployment-id
```
------
1. Teste o componente à medida que ele é executado no dispositivo principal do Greengrass. Ao concluir essa versão do componente, você pode carregá-lo no serviço AWS IoT Greengrass. Em seguida, você pode implantar o componente em outros dispositivos principais. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md).
# Publish components to deploy to your core devices
Depois de criar ou concluir uma versão de um componente, você pode publicá-la no serviço AWS IoT Greengrass. Em seguida, você pode implantá-lo nos dispositivos principais do Greengrass.
Se você usa a [CLI do Greengrass Development Kit (GDK CLI)](greengrass-development-kit-cli.md) para [desenvolver e criar um componente](create-components.md), você pode usar a [CLI do GDK](#publish-component-gdk-cli) para publicar o componente no Nuvem AWS. Caso contrário, [use os comandos shell integrados e o AWS CLI](#publish-component-shell-commands) para publicar o componente.
Você também pode usar o AWS CloudFormation para criar componentes e outros recursos da AWS a partir de modelos. Para obter mais informações, consulte [O que é o AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) e [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html) no *Guia do usuário do AWS CloudFormation*.
**Topics**
+ [Publicar um componente (GDK CLI)](#publish-component-gdk-cli)
+ [Publicar um componente (comandos shell)](#publish-component-shell-commands)
## Publicar um componente (GDK CLI)
Siga as instruções nesta seção para publicar um componente usando a CLI do GDK. A CLI do GDK carrega artefatos de construção em um bucket do S3, atualiza os URIs do artefato na fórmula e cria o componente a partir da fórmula. Você especifica o bucket e a região do S3 a serem usados no [arquivo de configuração da CLI do GDK](gdk-cli-configuration-file.md).
Se você usar a CLI do GDK v1.1.0 ou posterior, poderá especificar o argumento `--bucket` para especificar o bucket do S3 em que a CLI do GDK carrega os artefatos do componente. Se você não especificar esse argumento, a CLI do GDK será carregada no bucket do S3 cujo nome é `bucket-region-accountId`, em que *bucket* e *região* são os valores que você especifica em `gdk-config.json`, e *accountId* é seu ID da Conta da AWS. A CLI do GDK criará o bucket, se ele não existir.
**Importante**
As funções principais do dispositivo não permitem acesso aos buckets do S3 por padrão. Se for a primeira vez que você usa esse bucket do S3, você deve adicionar permissões à função para permitir que os dispositivos principais recuperem artefatos de componentes desse bucket do S3. Para obter mais informações, consulte [Permitir acesso aos buckets do S3 para artefatos de componentes](device-service-role.md#device-service-role-access-s3-bucket).
**Para publicar um componente do Greengrass (GDK CLI)**
1. Abra a pasta do componente em um prompt de comando ou terminal.
1. Caso ainda não tenha feito, crie o componente Greengrass. O comando de [compilação do componente](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build) produz uma fórmula e artefatos na pasta `greengrass-build` contida na pasta do componente. Execute o comando a seguir.
```
gdk component build
```
1. Publique o componente no Nuvem AWS. O comando de [publicação do componente](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-publish) carrega os artefatos do componente no Amazon S3 e atualiza a fórmula do componente com o URI de cada artefato. Em seguida, ele cria o componente no serviço AWS IoT Greengrass.
**nota**
O AWS IoT Greengrass calcula o resumo de cada artefato quando você cria o componente. Isso significa que você não pode modificar os arquivos de artefatos em seu bucket do S3 depois de criar um componente. Se você fizer isso, as implantações que incluam esse componente falharão, porque o resumo do arquivo não corresponde. Se você modificar um arquivo de artefato, deverá criar uma nova versão do componente.
Se você especificar `NEXT_PATCH` para a versão do componente no arquivo de configuração da CLI do GDK, a CLI do GDK usará a próxima versão do patch que ainda não existe no serviço AWS IoT Greengrass.
Execute o comando a seguir.
```
gdk component publish
```
A saída informa a versão do componente que a CLI do GDK criou.
Depois de publicar o componente, você pode implantá-los em dispositivos principais. Para obter mais informações, consulte [Implemente AWS IoT Greengrass componentes em dispositivos](manage-deployments.md).
## Publicar um componente (comandos shell)
Use o procedimento a seguir para publicar um componente usando comandos shell e o AWS Command Line Interface (AWS CLI). Ao publicar um componente, faça o seguinte:
1. Publique artefatos de componentes em um bucket do S3.
1. Adicione o URI do Amazon S3 de cada artefato à fórmula do componente.
1. Crie uma versão do componente no AWS IoT Greengrass a partir da fórmula do componente.
**nota**
Cada versão do componente que você carrega deve ser exclusiva. Certifique-se de fazer o upload da versão correta do componente, pois você não poderá editá-la depois de carregá-la.
Você pode seguir estas etapas para publicar um componente do seu computador de desenvolvimento ou do seu dispositivo principal do Greengrass.
**Para publicar um componente (comandos shell)**
1. Se o componente usar uma versão que existe no serviço AWS IoT Greengrass, você deverá alterar a versão do componente. Abra a fórmula em um editor de texto, incremente a versão e salve o arquivo. Escolha uma nova versão que reflita as alterações feitas no componente.
**nota**
O AWS IoT Greengrass usa versões semânticas para componentes. As versões semânticas seguem um sistema de numeração *principal*.*secundária*.*patch*. Por exemplo, a versão `1.0.0` representa a primeira versão principal de um componente. Para mais informações, consulte a [especificação de versão semântica](https://semver.org/).
1. Se seu componente tiver artefatos, faça o seguinte:
1. Publique os artefatos do componente em um bucket do S3 em sua Conta da AWS.
**dica**
Recomendamos que você inclua o nome e a versão do componente no caminho para o artefato no bucket do S3. Esse esquema de nomenclatura pode ajudar você a manter os artefatos que as versões anteriores do componente usam, para que você possa continuar oferecendo suporte às versões anteriores do componente.
Execute o comando a seguir para publicar um arquivo de artefato em um bucket do S3. Substitua amzn-s3-demo-bucket pelo nome do bucket e substitua *artifacts/com.example.HelloWorld/1.0.0/artifact.py* pelo caminho para o arquivo do artefato.
```
aws s3 cp artifacts/com.example.HelloWorld/1.0.0/artifact.py s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py
```
**Importante**
As funções principais do dispositivo não permitem acesso aos buckets do S3 por padrão. Se for a primeira vez que você usa esse bucket do S3, você deve adicionar permissões à função para permitir que os dispositivos principais recuperem artefatos de componentes desse bucket do S3. Para obter mais informações, consulte [Permitir acesso aos buckets do S3 para artefatos de componentes](device-service-role.md#device-service-role-access-s3-bucket).
1. Adicione uma lista nomeada `Artifacts` à fórmula do componente se ela não estiver presente. A lista `Artifacts` aparece em cada manifesto, que define os requisitos do componente em cada plataforma que ele suporta (ou os requisitos padrão do componente para todas as plataformas).
1. Adicione cada artefato à lista de artefatos ou atualize o URI dos artefatos existentes. O URI do Amazon S3 é composto pelo nome do bucket e pelo caminho para o objeto de artefato no bucket. Os URIs do Amazon S3 de seus artefatos devem ser semelhantes ao exemplo a seguir.
```
s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py
```
Depois de concluir essas etapas, sua fórmula deve ter uma lista `Artifacts` semelhante à seguinte.
------
#### [ JSON ]
```
{
...
"Manifests": [
{
"Lifecycle": {
...
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py",
"Unarchive": "NONE"
}
]
}
]
}
```
**nota**
Você pode adicionar a opção `"Unarchive": "ZIP"` de um artefato ZIP para configurar o software AWS IoT Greengrass Core para descompactar o artefato quando o componente for implantado.
------
#### [ YAML ]
```
...
Manifests:
- Lifecycle:
...
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py
Unarchive: NONE
```
**nota**
Você pode usar a opção `Unarchive: ZIP` de configurar o software AWS IoT Greengrass Core para descompactar um artefato ZIP quando o componente for implantado. Para obter mais informações sobre como usar artefatos ZIP em um componente, consulte a [variável de fórmula artifacts:decompressedPath](component-recipe-reference.md#component-recipe-artifacts-decompressed-path).
------
Para obter mais informações sobre receitas, consulte [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md).
1. Use o console do AWS IoT Greengrass para criar um componente a partir do arquivo de fórmula.
Execute o comando a seguir para criar o componente a partir de um arquivo de fórmula. Esse comando cria o componente e o publica como um componente AWS IoT Greengrass privado na sua Conta da AWS. Substitua *path/to/recipeFile* pelo caminho para o arquivo de fórmula.
```
aws greengrassv2 create-component-version --inline-recipe fileb://path/to/recipeFile
```
Copie `arn` da resposta para verificar o estado do componente na próxima etapa.
**nota**
O AWS IoT Greengrass calcula o resumo de cada artefato quando você cria o componente. Isso significa que você não pode modificar os arquivos de artefatos em seu bucket do S3 depois de criar um componente. Se você fizer isso, as implantações que incluam esse componente falharão, porque o resumo do arquivo não corresponde. Se você modificar um arquivo de artefato, deverá criar uma nova versão do componente.
1. Cada componente no serviço do AWS IoT Greengrass tem um estado. Execute o comando a seguir para confirmar o estado da versão do componente que você publica neste procedimento. Substitua *com.example.HelloWorld* e *1.0.0* pela versão do componente a ser consultada. Substitua `arn` pelo ARN da etapa anterior.
```
aws greengrassv2 describe-component --arn "arn:aws:greengrass:region:account-id:components:com.example.HelloWorld:versions:1.0.0"
```
A operação retorna uma resposta contendo os metadados do componente. Os metadados contêm um objeto `status` que contém o estado do componente e quaisquer erros, se aplicável.
Quando o estado do componente é `DEPLOYABLE`, você pode implantar o componente em dispositivos. Para obter mais informações, consulte [Implemente AWS IoT Greengrass componentes em dispositivos](manage-deployments.md).
# Interaja com AWS os serviços
Os dispositivos principais do Greengrass usam certificados X.509 para se conectar ao AWS IoT Core usando protocolos de autenticação TLS mútuos. Esses certificados permitem que os dispositivos interajam AWS IoT sem AWS credenciais, que normalmente incluem um ID de chave de acesso e em uma chave de acesso secreta. Outros produtos da AWS exigem credenciais da AWS em vez de certificados X.509 para chamar operações de API nos endpoints do serviço. O AWS IoT Core tem um provedor de credenciais que permite que os dispositivos usem seu certificado X.509 para autenticar solicitações da AWS. O provedor de credenciais do AWS IoT autentica os dispositivos usando um certificado X.509 e emite credenciais da AWS na forma de um token de segurança temporário e de privilégio limitado. Os dispositivos podem usar esse token para assinar e autenticar qualquer AWS solicitação da. Isso elimina a necessidade de armazenar AWS credenciais nos dispositivos principais do Greengrass. Para mais informações, consulte [Autorizar de chamadas diretas para serviços da AWS](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) no *Guia do desenvolvedor do AWS IoT Core*.
Para obter credenciais do AWS IoT Greengrass, os dispositivos principais usam um alias de função que aponta para uma AWS IoT função do IAM. Essa função do IAM é chamada de *função de troca de tokens*. Você cria o alias da função e a função de troca de tokens ao instalar o software AWS IoT Greengrass Core. Para especificar o alias de função que um dispositivo principal usa, configure o parâmetro `iotRoleAlias` do [Greengrass nucleus](greengrass-nucleus-component.md).
O provedor de AWS IoT credenciais assume a função de troca de tokens em seu nome para fornecer AWS credenciais aos dispositivos principais. Você pode anexar políticas apropriadas do IAM a essa função para permitir que seus dispositivos principais acessem seus AWS recursos, como artefatos de componentes em buckets do S3. Para mais informações sobre como configurar o perfil de troca de tokens, consulte [Autorize os dispositivos principais a interagir com os serviços AWS](device-service-role.md).
Os principais dispositivos do Greengrass armazenam AWS as credenciais na memória e, por padrão, as credenciais expiram após uma hora. Se o software AWS IoT Greengrass principal for reiniciado, ele deverá buscar as credenciais novamente. Você pode usar a operação [UpdateRoleAlias](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateRoleAlias.html) para configurar a duração em que as credenciais são válidas.
O AWS IoT Greengrass fornece um componente público, o componente do serviço de troca de tokens, que você pode definir como uma dependência em seu componente personalizado para interagir com os produtos da AWS. O serviço de troca de tokens fornece ao seu componente uma variável de ambiente,`AWS_CONTAINER_CREDENTIALS_FULL_URI`, que define o URI para um servidor local que fornece AWS credenciais. Quando você cria um cliente AWS SDK, o cliente verifica essa variável de ambiente e se conecta ao servidor local para recuperar AWS as credenciais e as usa para assinar solicitações de API. Isso permite que você use AWS SDKs e outras ferramentas para chamar AWS serviços em seus componentes. Para obter mais informações, consulte [Serviço de troca de token](token-exchange-service-component.md).
**Importante**
Em 13 de julho de 2016, o suporte para adquirir credenciais da AWS dessa forma foi incluído nos AWS SDKs. Seu componente deve usar uma versão do AWS SDK criada a partir dessa data. Para obter mais informações, consulte [Como usar um AWS SDK com suporte](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html#task-iam-roles-minimum-sdk) no *Guia do desenvolvedor do Amazon Elastic Container Service*.
Para adquirir credenciais da AWS em seu componente personalizado, defina `aws.greengrass.TokenExchangeService` como uma dependência na fórmula do componente. O exemplo de fórmula a seguir define um componente que instala o [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) e executa um script Python que usa credenciais da AWS do serviço de troca de tokens para listar buckets do Amazon S3.
**nota**
Para executar esse componente de exemplo, seu dispositivo deve ter a `s3:ListAllMyBuckets` permissão. Para obter mais informações, consulte [Autorize os dispositivos principais a interagir com os serviços AWS](device-service-role.md).
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.ListS3Buckets",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that uses the token exchange service to list S3 buckets.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "pip3 install --user boto3",
"Run": "python3 -u {artifacts:path}/list_s3_buckets.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"install": "pip3 install --user boto3",
"Run": "py -3 -u {artifacts:path}/list_s3_buckets.py"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.ListS3Buckets
ComponentVersion: '1.0.0'
ComponentDescription: A component that uses the token exchange service to list S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.TokenExchangeService:
VersionRequirement: '^2.0.0'
DependencyType: HARD
Manifests:
- Platform:
os: linux
Lifecycle:
install:
pip3 install --user boto3
Run: |-
python3 -u {artifacts:path}/list_s3_buckets.py
- Platform:
os: windows
Lifecycle:
install:
pip3 install --user boto3
Run: |-
py -3 -u {artifacts:path}/list_s3_buckets.py
```
------
Esse componente de exemplo executa o seguinte script Python, `list_s3_buckets.py` que lista os buckets do Amazon S3.
```
import boto3
import os
try:
print("Creating boto3 S3 client...")
s3 = boto3.client('s3')
print("Successfully created boto3 S3 client")
except Exception as e:
print("Failed to create boto3 s3 client. Error: " + str(e))
exit(1)
try:
print("Listing S3 buckets...")
response = s3.list_buckets()
for bucket in response['Buckets']:
print(f'\t{bucket["Name"]}')
print("Successfully listed S3 buckets")
except Exception as e:
print("Failed to list S3 buckets. Error: " + str(e))
exit(1)
```
# Executar um contêiner do Docker
Você pode configurar AWS IoT Greengrass componentes para executar um contêiner [Docker](https://www.docker.com/) a partir de imagens armazenadas nos seguintes locais:
+ Repositórios de imagem públicos e privados no Amazon Elastic Container Registry (Amazon ECR)
+ Repositório público do Docker Hub
+ Registro confiável e público do Docker
+ Bucket do S3
Em seu componente personalizado, inclua o URI da imagem do Docker como um artefato para recuperar a imagem e executá-la no dispositivo principal. Para imagens do Amazon ECR e do Docker Hub, você pode usar o componente [gerenciador de aplicativos do Docker](docker-application-manager-component.md) para baixar as imagens e gerenciar credenciais para repositórios privados do Amazon ECR.
**Topics**
+ [Requisitos](#run-docker-container-requirements)
+ [Execute um contêiner do Docker a partir de uma imagem pública no Amazon ECR ou Docker Hub](#run-docker-container-public-ecr-dockerhub)
+ [Executar um contêiner do Docker a partir de uma imagem privada no Amazon ECR](#run-docker-container-private-ecr)
+ [Executar um contêiner do Docker a partir de uma imagem no Amazon S3](#run-docker-container-s3)
+ [Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
+ [Use AWS credenciais em componentes de contêiner do Docker (Linux)](#docker-container-token-exchange-service)
+ [Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)](#docker-container-stream-manager)
## Requisitos
Para executar um contêiner do Docker em um componente, você precisa:
+ Um dispositivo principal do Greengrass. Se você não tiver uma, consulte [Tutorial: Conceitos básicos do AWS IoT Greengrass V2](getting-started.md).
+ [Docker Engine](https://docs.docker.com/engine/) 1.9.1 ou versão posterior instalado no dispositivo principal do Greengrass. A versão 20.10 é a versão mais recente verificada para funcionar com o software AWS IoT Greengrass Core. É preciso instalar o Docker diretamente no dispositivo principal antes de implantar componentes que executam contêineres do Docker.
**dica**
Também é possível configurar o dispositivo principal para instalar o Docker Engine quando o componente for instalado. Por exemplo, o script de instalação a seguir instala o Docker Engine antes de carregar a imagem do Docker. Esse script de instalação funciona em distribuições Linux baseadas no Debian, como o Ubuntu. Se você configurar o componente para instalar o Docker Engine com esse comando, talvez seja necessário configurar o `RequiresPrivilege` como `true` no script do ciclo de vida para executar a instalação e os comandos `docker`. Para obter mais informações, consulte [AWS IoT Greengrass referência da receita do componente](component-recipe-reference.md).
```
apt-get install docker-ce docker-ce-cli containerd.io && docker load -i {artifacts:path}/hello-world.tar
```
+ O usuário do sistema que executa um componente de contêiner do Docker deve ter permissões de raiz ou administrador, ou é necessário configurar o Docker para executá-lo como usuário não raiz ou não administrador.
+ Em dispositivos Linux, você pode adicionar um usuário ao grupo `docker` para chamar os comandos `docker` sem `sudo`.
+ Em dispositivos Windows, é possível adicionar um usuário ao grupo `docker-users` para chamar comandos do `docker` sem privilégios de administrador.
------
#### [ Linux or Unix ]
Para adicionar `ggc_user` ou o usuário não raiz que você usa para executar componentes de contêiner do Docker ao grupo de `docker`, execute o seguinte comando.
```
sudo usermod -aG docker ggc_user
```
Para obter mais informações, consulte [Gerenciar o Docker como um usuário não raiz](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
------
#### [ Windows Command Prompt (CMD) ]
Para adicionar `ggc_user` ou o usuário que você usa para executar componentes de contêiner do Docker ao grupo de `docker-users`, execute o seguinte comando como administrador.
```
net localgroup docker-users ggc_user /add
```
------
#### [ Windows PowerShell ]
Para adicionar `ggc_user` ou o usuário que você usa para executar componentes de contêiner do Docker ao grupo de `docker-users`, execute o seguinte comando como administrador.
```
Add-LocalGroupMember -Group docker-users -Member ggc_user
```
------
+ Arquivos acessados pelo componente de contêiner do Docker [montado como um volume](https://docs.docker.com/storage/volumes/) no contêiner do Docker.
+ Se você [configurar o software AWS IoT Greengrass Core para usar um proxy de rede](configure-greengrass-core-v2.md#configure-alpn-network-proxy), deverá [configurar o Docker para usar o mesmo servidor proxy](https://docs.docker.com/network/proxy/).
Além desses requisitos, você também deve atender aos seguintes requisitos se eles se aplicarem ao seu ambiente:
+ Para usar o [Docker Compose](https://docs.docker.com/compose/) para criar e iniciar seus contêineres do Docker, instale o Docker Compose em seu dispositivo principal do Greengrass e carregue seu arquivo do Docker Compose em um bucket do S3. Você deve armazenar seu arquivo Compose em um bucket do S3 no mesmo componente Conta da AWS e no Região da AWS mesmo. Para ver um exemplo que usa o comando `docker-compose up` em um componente personalizado, consulte [Execute um contêiner do Docker a partir de uma imagem pública no Amazon ECR ou Docker Hub](#run-docker-container-public-ecr-dockerhub).
+ [Se você estiver executando AWS IoT Greengrass por trás de um proxy de rede, configure o daemon do Docker para usar um servidor proxy.](https://docs.docker.com/network/proxy/)
+ Se suas imagens do Docker estiverem armazenadas no Amazon ECR ou no Docker Hub, inclua o componente [gerenciador de componentes do Docker](docker-application-manager-component.md) como uma dependência em seu componente de contêiner do Docker. Inicie o daemon do Docker no dispositivo principal antes de implantar o componente.
Além disso, inclua a imagem URIs como artefatos componentes. A imagem URIs deve estar no formato `docker:registry/image[:tag|@digest]` mostrado nos exemplos a seguir:
+ Imagem privada do Amazon ECR: `docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]`
+ Imagem pública do Amazon ECR: `docker:public.ecr.aws/repository/image[:tag|@digest]`
+ Imagem pública do Docker Hub: `docker:name[:tag|@digest]`
Para obter mais informações sobre como executar contêineres do Docker a partir de imagens armazenadas em repositórios públicos, consulte [Execute um contêiner do Docker a partir de uma imagem pública no Amazon ECR ou Docker Hub](#run-docker-container-public-ecr-dockerhub).
+ Se suas imagens do Docker estiverem armazenadas em um repositório privado do Amazon ECR, será preciso incluir o componente do serviço de troca de tokens como uma dependência no componente do contêiner do Docker. Além disso, o [perfil de dispositivo do Greengrass](device-service-role.md) precisa permitir as ações `ecr:GetAuthorizationToken`, `ecr:BatchGetImage` e `ecr:GetDownloadUrlForLayer`, conforme mostrado no seguinte exemplo de política do IAM.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
```
------
Para obter informações sobre como executar contêineres do Docker a partir de imagens armazenadas em um repositório privado do Amazon ECR, consulte [Executar um contêiner do Docker a partir de uma imagem privada no Amazon ECR](#run-docker-container-private-ecr).
+ Para usar imagens do Docker armazenadas em um repositório privado do Amazon ECR, o repositório privado deve estar no mesmo que o dispositivo principal Região da AWS .
+ Se suas imagens do Docker ou arquivos do Compose estiverem armazenados em um bucket do S3, o [perfil de dispositivo do Greengrass](device-service-role.md) deve oferecer a permissão `s3:GetObject` para permitir que os dispositivos principais baixem as imagens como artefatos de componentes, conforme mostrado no exemplo de política do IAM a seguir.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
```
------
Para obter informações sobre como executar contêineres do Docker a partir de imagens armazenadas no Amazon S3, consulte [Executar um contêiner do Docker a partir de uma imagem no Amazon S3](#run-docker-container-s3).
+ Para usar comunicação entre processos (IPC), credenciais da AWS ou gerenciador de fluxos em seu componente de contêiner do Docker, você deve especificar opções adicionais ao executar o contêiner do Docker. Para saber mais, consulte:
+ [Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
+ [Use AWS credenciais em componentes de contêiner do Docker (Linux)](#docker-container-token-exchange-service)
+ [Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)](#docker-container-stream-manager)
## Execute um contêiner do Docker a partir de uma imagem pública no Amazon ECR ou Docker Hub
Esta seção descreve como você pode criar um componente personalizado que usa o Docker Compose para executar um contêiner do Docker a partir de imagens do Docker armazenadas no Amazon ECR e no Docker Hub.
**Para executar um contêiner do Docker usando o Docker Compose**
1. Crie e faça upload de um arquivo Docker Compose para um bucket do Amazon S3. Certifique-se de que o [perfil de dispositivo do Greengrass](device-service-role.md) conceda a permissão `s3:GetObject` para que o dispositivo acesse o arquivo do Compose. O exemplo de arquivo Compose mostrado no exemplo a seguir inclui a imagem do Amazon CloudWatch Agent do Amazon ECR e a imagem do MySQL do Docker Hub.
```
version: "3"
services:
cloudwatchagent:
image: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
mysql:
image: "mysql:8.0"
```
1. [Crie um componente personalizado](create-components.md) em seu dispositivo AWS IoT Greengrass principal. A fórmula de exemplo mostrada no exemplo a seguir tem as seguintes propriedades:
+ O componente do gerenciador de aplicações Docker como uma dependência. Esse componente permite que o AWS IoT Greengrass baixe imagens dos repositórios públicos do Amazon ECR e do Docker Hub.
+ Um artefato de componente que especifica uma imagem do Docker em um repositório público do Amazon ECR.
+ Um artefato de componente que especifica uma imagem do Docker em um repositório público do Docker Hub.
+ Um artefato de componente que especifica o arquivo do Docker Compose que inclui contêineres para as imagens do Docker que você deseja executar.
+ Um script de execução do ciclo de vida que usa [docker-compose up](https://docs.docker.com/compose/reference/up/) para criar e iniciar um contêiner a partir das imagens especificadas.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyDockerComposeComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker-compose -f {artifacts:path}/docker-compose.yaml up"
},
"Artifacts": [
{
"URI": "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
},
{
"URI": "docker:mysql:8.0"
},
{
"URI": "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyDockerComposeComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker-compose -f {artifacts:path}/docker-compose.yaml up
Artifacts:
- URI: "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
- URI: "docker:mysql:8.0"
- URI: "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
```
------
**nota**
Para usar comunicação entre processos (IPC), credenciais da AWS ou gerenciador de fluxos em seu componente de contêiner do Docker, você deve especificar opções adicionais ao executar o contêiner do Docker. Para saber mais, consulte:
[Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
[Use AWS credenciais em componentes de contêiner do Docker (Linux)](#docker-container-token-exchange-service)
[Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)](#docker-container-stream-manager)
1. [Teste o componente](test-components.md) para verificar se ele funciona conforme o esperado.
**Importante**
É necessário instalar e iniciar o daemon do Docker antes de implantar o componente.
Depois de implantar o componente localmente, você pode executar o comando [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) para verificar se o contêiner está sendo executado.
```
docker container ls
```
1. Quando o componente estiver pronto, faça o upload do componente AWS IoT Greengrass para implantá-lo em outros dispositivos principais. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md).
## Executar um contêiner do Docker a partir de uma imagem privada no Amazon ECR
Esta seção descreve como criar um componente personalizado que executa um contêiner do Docker a partir de uma imagem do Docker armazenada em um repositório privado no Amazon ECR.
**Para executar um contêiner do Docker**
1. [Crie um componente personalizado](create-components.md) em seu dispositivo AWS IoT Greengrass principal. Use a fórmula de exemplo a seguir, que tem as seguintes propriedades:
+ O componente do gerenciador de aplicações Docker como uma dependência. Esse componente permite que o AWS IoT Greengrass gerencie credenciais para baixar imagens de repositórios privados.
+ O componente do serviço de troca de tokens como uma dependência. Esse componente permite recuperar AWS credenciais AWS IoT Greengrass para interagir com o Amazon ECR.
+ Um artefato de componente que especifica uma imagem do Docker em um repositório privado do Amazon ECR.
+ Um script de execução do ciclo de vida que usa [docker run](https://docs.docker.com/engine/reference/commandline/run/) para criar e iniciar um contêiner a partir da imagem.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyPrivateDockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from a private Amazon ECR image.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
},
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
},
"Artifacts": [
{
"URI": "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyPrivateDockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from a private Amazon ECR image.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
aws.greengrass.TokenExchangeService:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]
Artifacts:
- URI: "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
```
------
**nota**
Para usar comunicação entre processos (IPC), credenciais da AWS ou gerenciador de fluxos em seu componente de contêiner do Docker, você deve especificar opções adicionais ao executar o contêiner do Docker. Para saber mais, consulte:
[Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
[Use AWS credenciais em componentes de contêiner do Docker (Linux)](#docker-container-token-exchange-service)
[Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)](#docker-container-stream-manager)
1. [Teste o componente](test-components.md) para verificar se ele funciona conforme o esperado.
**Importante**
É necessário instalar e iniciar o daemon do Docker antes de implantar o componente.
Depois de implantar o componente localmente, você pode executar o comando [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) para verificar se o contêiner está sendo executado.
```
docker container ls
```
1. Faça o upload do componente AWS IoT Greengrass para implantá-lo em outros dispositivos principais. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md).
## Executar um contêiner do Docker a partir de uma imagem no Amazon S3
Esta seção descreve como executar um contêiner do Docker em um compentne de uma imagem do Docker armazenada no Amazon S3.
**Para executar um contêiner do Docker em um componente de uma imagem no Amazon S3**
1. Execute o comando [docker save](https://docs.docker.com/engine/reference/commandline/save/) para criar um backup de um contêiner do Docker. Você fornece esse backup como um artefato de componente para executar o contêiner no AWS IoT Greengrass. *hello-world*Substitua pelo nome da imagem e *hello-world.tar* substitua pelo nome do arquivo a ser criado.
```
docker save hello-world > artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
```
1. [Crie um componente personalizado](create-components.md) em seu dispositivo AWS IoT Greengrass principal. Use a fórmula de exemplo a seguir, que tem as seguintes propriedades:
+ Um script de instalação do ciclo de vida que usa [docker load para](https://docs.docker.com/engine/reference/commandline/load/) carregar uma imagem do Docker de um arquivo.
+ Um script de execução do ciclo de vida que usa [docker run](https://docs.docker.com/engine/reference/commandline/run/) para criar e iniciar um contêiner a partir da imagem. A opção `--rm` limpa o contêiner quando ele sair.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
```
------
**nota**
Para usar comunicação entre processos (IPC), credenciais da AWS ou gerenciador de fluxos em seu componente de contêiner do Docker, você deve especificar opções adicionais ao executar o contêiner do Docker. Para saber mais, consulte:
[Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
[Use AWS credenciais em componentes de contêiner do Docker (Linux)](#docker-container-token-exchange-service)
[Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)](#docker-container-stream-manager)
1. [Teste o componente](test-components.md) para verificar se ele funciona conforme o esperado.
Depois de implantar o componente localmente, você pode executar o comando [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) para verificar se o contêiner está sendo executado.
```
docker container ls
```
1. Quando o componente estiver pronto, faça o upload do arquivo de imagens do Docker em um bucket do S3 e adicione seu URI à fórmula do componente. Em seguida, você pode carregar o componente AWS IoT Greengrass para implantá-lo em outros dispositivos principais. Para obter mais informações, consulte [Publish components to deploy to your core devices](publish-components.md).
Quando você terminar, a fórmula do componente deve ser semelhante ao seguinte exemplo.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
```
------
## Usar comunicação entre processos nos componentes do contêiner do Docker
Você pode usar a biblioteca de comunicação entre processos (IPC) do Greengrass no AWS IoT Device SDK para se comunicar com o núcleo do Greengrass, outros componentes do Greengrass e. AWS IoT Core Para obter mais informações, consulte [Use o AWS IoT Device SDK para se comunicar com o núcleo do Greengrass, outros componentes e AWS IoT CoreComunique-se com o núcleo do Greengrass, outros componentes e AWS IoT Core](interprocess-communication.md).
Para usar o IPC em um componente de contêiner do Docker, você deve executar o contêiner do Docker com os seguintes parâmetros:
+ Monte o soquete IPC no contêiner. O núcleo do Greengrass fornece o caminho do arquivo do soquete IPC na variável de ambiente `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT`.
+ Defina as variáveis de ambiente `SVCUID` e `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` de acordo com os valores que o núcleo do Greengrass fornece aos componentes. Seu componente usa essas variáveis de ambiente para autenticar conexões com o núcleo do Greengrass.
**Example Exemplo de receita: publicar uma mensagem MQTT em AWS IoT Core (Python)**
A receita a seguir define um exemplo de componente de contêiner do Docker que publica uma mensagem MQTT no. AWS IoT Core Essa fórmula tem as seguintes propriedades:
+ Uma política de autorização (`accessControl`) que permite que o componente publique mensagens MQTT AWS IoT Core em todos os tópicos. Para obter mais informações, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies) e [autorização de IPC do MQTT do AWS IoT Core](ipc-iot-core-mqtt.md#ipc-iot-core-mqtt-authorization).
+ Um artefato de componente que especifica uma imagem do Docker como um arquivo TAR no Amazon S3.
+ Um script de instalação do ciclo de vida que carrega a imagem do Docker do arquivo TAR.
+ Um script de execução do ciclo de vida que executa um contêiner do Docker a partir da imagem. O comando [Docker run](https://docs.docker.com/engine/reference/run/) tem os seguintes argumentos:
+ O argumento `-v` monta o soquete IPC do Greengrass no contêiner.
+ Os dois primeiros argumentos `-e` definem as variáveis de ambiente necessárias no contêiner do Docker.
+ Os argumentos adicionais `-e` definem as variáveis de ambiente usadas neste exemplo.
+ O argumento `--rm` limpa o contêiner quando ele sair.
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.PublishToIoTCore",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses interprocess communication to publish an MQTT message to IoT Core.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"topic": "test/topic/java",
"message": "Hello, World!",
"qos": "1",
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.python.docker.PublishToIoTCore:pubsub:1": {
"policyDescription": "Allows access to publish to IoT Core on all topics.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/publish-to-iot-core.tar",
"Run": "docker run -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e SVCUID -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e MQTT_TOPIC=\"{configuration:/topic}\" -e MQTT_MESSAGE=\"{configuration:/message}\" -e MQTT_QOS=\"{configuration:/qos}\" --rm publish-to-iot-core"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.PublishToIoTCore
ComponentVersion: 1.0.0
ComponentDescription: Uses interprocess communication to publish an MQTT message to IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
topic: 'test/topic/java'
message: 'Hello, World!'
qos: '1'
accessControl:
aws.greengrass.ipc.mqttproxy:
'com.example.python.docker.PublishToIoTCore:pubsub:1':
policyDescription: Allows access to publish to IoT Core on all topics.
operations:
- 'aws.greengrass#PublishToIoTCore'
resources:
- '*'
Manifests:
- Platform:
os: all
Lifecycle:
install: 'docker load -i {artifacts:path}/publish-to-iot-core.tar'
Run: |
docker run \
-v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e SVCUID \
-e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e MQTT_TOPIC="{configuration:/topic}" \
-e MQTT_MESSAGE="{configuration:/message}" \
-e MQTT_QOS="{configuration:/qos}" \
--rm publish-to-iot-core
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar
```
## Use AWS credenciais em componentes de contêiner do Docker (Linux)
Você pode usar o [componente de serviço de troca de tokens](token-exchange-service-component.md) para interagir com AWS os serviços nos componentes do Greengrass. Esse componente fornece credenciais da AWS obtidas da [função de troca de tokens](device-service-role.md) do dispositivo principal usando um servidor de contêiner local. Para obter mais informações, consulte [Interaja com AWS os serviços](interact-with-aws-services.md).
**nota**
O exemplo nesta seção funciona somente nos dispositivos principais do Linux.
Para usar AWS as credenciais do serviço de troca de tokens em um componente de contêiner do Docker, você deve executar o contêiner do Docker com os seguintes parâmetros:
+ Forneça acesso à rede host usando o argumento `--network=host`. Essa opção permite que o contêiner do Docker se conecte ao serviço local de troca de tokens para recuperar AWS as credenciais. Esse argumento funciona somente no Docker para Linux.
**Atenção**
Essa opção dá ao contêiner acesso a todas as interfaces de rede local no host, portanto, essa opção é menos segura do que se você executasse contêineres do Docker sem esse acesso à rede host. Considere isso ao desenvolver e executar componentes de contêiner do Docker que usam essa opção. Para obter mais informações, consulte [Rede: host](https://docs.docker.com/engine/reference/run/#network-host) na *documentação do Docker*.
+ Defina as variáveis de `AWS_CONTAINER_AUTHORIZATION_TOKEN` ambiente `AWS_CONTAINER_CREDENTIALS_FULL_URI` e de acordo com os valores que o núcleo do Greengrass fornece aos componentes. AWS SDKs use essas variáveis de ambiente para recuperar as AWS credenciais.
**Example Exemplo de fórmula: listar buckets S3 em um componente de contêiner do Docker (Python)**
A fórmula a seguir define um exemplo de componente de contêiner do Docker que lista os buckets S3 em sua Conta da AWS. Essa fórmula tem as seguintes propriedades:
+ O componente do serviço de troca de tokens como uma dependência. Essa dependência permite que o componente recupere AWS credenciais para interagir com outros serviços. AWS
+ Um artefato de componente que especifica uma imagem do Docker como um arquivo TAR no Amazon S3.
+ Um script de instalação do ciclo de vida que carrega a imagem do Docker do arquivo TAR.
+ Um script de execução do ciclo de vida que executa um contêiner do Docker a partir da imagem. O comando [Docker run](https://docs.docker.com/engine/reference/run/) tem os seguintes argumentos:
+ O argumento `--network=host` fornece ao contêiner acesso à rede host, para que o contêiner possa se conectar ao serviço de troca de tokens.
+ O argumento `-e` define as variáveis de ambiente necessárias no contêiner do Docker.
+ O argumento `--rm` limpa o contêiner quando ele sair.
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.ListS3Buckets",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses the token exchange service to lists your S3 buckets.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/list-s3-buckets.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e AWS_CONTAINER_CREDENTIALS_FULL_URI --rm list-s3-buckets"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.ListS3Buckets
ComponentVersion: 1.0.0
ComponentDescription: Uses the token exchange service to lists your S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.TokenExchangeService:
VersionRequirement: ^2.0.0
DependencyType: HARD
Manifests:
- Platform:
os: linux
Lifecycle:
install: 'docker load -i {artifacts:path}/list-s3-buckets.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e AWS_CONTAINER_CREDENTIALS_FULL_URI \
--rm list-s3-buckets
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar
```
## Usar o gerenciador de fluxos em componentes de contêiner do Docker (Linux)
Você pode usar o [componente gerenciador de fluxos](stream-manager-component.md) para gerenciar fluxos de dados nos componentes do Greengrass. Esse componente permite que você processe fluxos de dados e transfira dados de IoT de alto volume para o. Nuvem AWS AWS IoT Greengrass fornece um SDK do gerenciador de stream que você usa para interagir com o componente do gerenciador de stream. Para obter mais informações, consulte [Gerenciar fluxos de dados no nos dispositivos principais do Greengrass](manage-data-streams.md).
**nota**
O exemplo nesta seção funciona somente nos dispositivos principais do Linux.
Para usar o SDK do gerenciador de fluxos em um componente de contêiner do Docker, você deve executar o contêiner do Docker com os seguintes parâmetros:
+ Forneça acesso à rede host usando o argumento `--network=host`. Essa opção permite que o contêiner do Docker interaja com o componente gerenciador de fluxos por meio de uma conexão TLS local. Esse argumento funciona somente no Docker para Linux
**Atenção**
Essa opção dá ao contêiner acesso a todas as interfaces de rede local no host, portanto, essa opção é menos segura do que se você executasse contêineres do Docker sem esse acesso à rede host. Considere isso ao desenvolver e executar componentes de contêiner do Docker que usam essa opção. Para obter mais informações, consulte [Rede: host](https://docs.docker.com/engine/reference/run/#network-host) na *documentação do Docker*.
+ Se você configurar o componente do gerenciador de fluxos para exigir autenticação, que é o comportamento padrão, defina a variável de ambiente `AWS_CONTAINER_CREDENTIALS_FULL_URI` com o valor que o núcleo do Greengrass fornece aos componentes. Para obter mais informações, consulte a [configuração do gerenciador de fluxos](stream-manager-component.md#stream-manager-component-configuration).
+ Se você configurar o componente do gerenciador de fluxos com uma porta diferente do padrão, deverá usar a [comunicação entre processos (IPC)](interprocess-communication.md) para recuperar a porta da configuração do gerenciador de fluxos. Execute o contêiner do Docker com opções adicionais para usar a IPC. Para saber mais, consulte:
+ [Conectar-se ao gerenciador de fluxos no código da aplicação](use-stream-manager-in-custom-components.md#connect-to-stream-manager)
+ [Usar comunicação entre processos nos componentes do contêiner do Docker](#docker-container-ipc)
**Example Exemplo de fórmula: transmitir um arquivo para um bucket do S3 em um componente de contêiner do Docker (Python)**
A fórmula a seguir define um exemplo de componente de contêiner do Docker que cria um arquivo e o transmite para um bucket do S3. Essa fórmula tem as seguintes propriedades:
+ O componente do gerenciador de fluxos como uma dependência. Essa dependência permite que o componente use o SDK do gerenciador de fluxos para interagir com o componente do gerenciador de fluxos.
+ Um artefato de componente que especifica uma imagem do Docker como um arquivo TAR no Amazon S3.
+ Um script de instalação do ciclo de vida que carrega a imagem do Docker do arquivo TAR.
+ Um script de execução do ciclo de vida que executa um contêiner do Docker a partir da imagem. O comando [Docker run](https://docs.docker.com/engine/reference/run/) tem os seguintes argumentos:
+ O argumento `--network=host` fornece ao contêiner acesso à rede host, para que o contêiner possa se conectar ao componente do gerenciador de fluxos.
+ O primeiro argumento `-e` define a variável de ambiente `AWS_CONTAINER_AUTHORIZATION_TOKEN` necessária no contêiner do Docker.
+ Os argumentos adicionais `-e` definem as variáveis de ambiente usadas neste exemplo.
+ O argumento `-v` monta a [pasta de trabalho](component-recipe-reference.md#component-recipe-work-path) do componente no contêiner. Esse exemplo cria um arquivo na pasta de trabalho para fazer o upload desse arquivo para o Amazon S3 usando o gerenciador de fluxos.
+ O argumento `--rm` limpa o contêiner quando ele sair.
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.StreamFileToS3",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Creates a text file and uses stream manager to stream the file to S3.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"ComponentConfiguration": {
"DefaultConfiguration": {
"bucketName": ""
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/stream-file-to-s3.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e BUCKET_NAME=\"{configuration:/bucketName}\" -e WORK_PATH=\"{work:path}\" -v {work:path}:{work:path} --rm stream-file-to-s3"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.StreamFileToS3
ComponentVersion: 1.0.0
ComponentDescription: Creates a text file and uses stream manager to stream the file to S3.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: ^2.0.0
DependencyType: HARD
ComponentConfiguration:
DefaultConfiguration:
bucketName: ''
Manifests:
- Platform:
os: linux
Lifecycle:
install: 'docker load -i {artifacts:path}/stream-file-to-s3.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e BUCKET_NAME="{configuration:/bucketName}" \
-e WORK_PATH="{work:path}" \
-v {work:path}:{work:path} \
--rm stream-file-to-s3
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar
```
# AWS IoT Greengrass referência da receita do componente
A fórmula do componente é um arquivo que define os detalhes, dependências, artefatos e ciclos de vida de um componente. O *ciclo de vida* do componente especifica os comandos a serem executados para instalar, executar e desligar o componente, por exemplo. O AWS IoT Greengrass núcleo usa os ciclos de vida que você define na receita para instalar e executar componentes. O AWS IoT Greengrass serviço usa a receita para identificar as dependências e os artefatos a serem implantados em seus dispositivos principais quando você implanta o componente.
Na fórmula, é possível definir dependências e ciclos de vida exclusivos para cada plataforma que um componente suporta. Use esse recurso para implantar um componente em dispositivos com várias plataformas que tenham requisitos diferentes. Você também pode usar isso para evitar a instalação AWS IoT Greengrass de um componente em dispositivos que não o suportam.
Cada fórmula contém uma lista de *manifestos*. Cada manifesto especifica um conjunto de requisitos da plataforma, o ciclo de vida e os artefatos a serem usados nos dispositivos principais cuja plataforma atende a esses requisitos. O dispositivo principal usa o primeiro manifesto com os requisitos de plataforma que o dispositivo atende. Especifique um manifesto sem nenhum requisito de plataforma que corresponda a qualquer dispositivo principal.
Também é possível especificar um ciclo de vida global que não esteja em um manifesto. No ciclo de vida global, é possível usar *chaves de seleção* que identificam subseções do ciclo de vida. Em seguida, é possível especificar essas chaves de seleção em um manifesto para usar essas seções do ciclo de vida global, além do ciclo de vida do manifesto. O dispositivo principal usa as chaves de seleção do manifesto somente se ele não definir um ciclo de vida. Use a seleção `all` em um manifesto para combinar seções do ciclo de vida global sem chaves de seleção.
Depois que o software AWS IoT Greengrass Core seleciona um manifesto que corresponda ao dispositivo principal, ele faz o seguinte para identificar as etapas do ciclo de vida a serem usadas:
+ Se o manifesto selecionado definir um ciclo de vida, o dispositivo principal usará esse ciclo de vida.
+ Se o manifesto selecionado não definir um ciclo de vida, o dispositivo principal usará esse ciclo de vida. O dispositivo principal faz o seguinte para identificar quais seções do ciclo de vida global usar:
+ Se o manifesto definir chaves de seleção, o dispositivo principal usará as seções do ciclo de vida global que contêm as chaves de seleção do manifesto.
+ Se o manifesto não definir chaves de seleção, o dispositivo principal usará as seções do ciclo de vida global que não contêm as chaves de seleção. Esse comportamento é equivalente a um manifesto que define a seleção `all`.
**Importante**
Um dispositivo principal deve atender aos requisitos de plataforma de pelo menos um manifesto para instalar o componente. Se nenhum manifesto corresponder ao dispositivo principal, o software AWS IoT Greengrass Core não instalará o componente e a implantação falhará.
É possível definir fórmulas no formato [JSON](https://en.wikipedia.org/wiki/JSON) ou [YAML](https://en.wikipedia.org/wiki/YAML). A seção de exemplos de fórmulas inclui fórmulas em cada formato.
**Topics**
+ [Validação da fórmula](#recipe-validation)
+ [Formato da fórmula](#recipe-format)
+ [Variáveis da fórmula](#recipe-variables)
+ [Exemplos de fórmula](#recipe-examples)
## Validação da fórmula
O Greengrass valida uma fórmula de componente JSON ou YAML ao criar uma versão do componente. Essa validação verifica se há erros comuns na fórmula do componente JSON ou YAML para evitar possíveis problemas de implantação. A validação verifica a fórmula em busca de erros comuns (por exemplo, vírgulas, chaves e campos ausentes) e para garantir que ela esteja bem formada.
Se você receber uma mensagem de erro de validação da fórmula, verifique se há vírgulas, chaves ou campos ausentes nela. Verifique se não está faltando nenhum campo examinando o [formato da fórmula](#recipe-format).
## Formato da fórmula
Ao definir uma fórmula para um componente, você especifica as seguintes informações no documento dela. A mesma estrutura se aplica às fórmulas nos formatos YAML e JSON.
`RecipeFormatVersion`
A versão modelo para a fórmula. Escolha a seguinte opção:
+ `2020-01-25`
`ComponentName`
O nome do componente definido por essa fórmula. O nome do componente deve ser exclusivo Conta da AWS em cada região.
**Dicas**
+ Use o formato de nome de domínio inverso para evitar colisões de nomes dentro da empresa. Por exemplo, se sua empresa é dona do `example.com` e você trabalha em um projeto de energia solar, é possível nomear seu componente Hello World como `com.example.solar.HelloWorld`. Isso ajuda a evitar colisões de nomes de componentes na empresa.
+ Evite o prefixo `aws.greengrass` nos nomes dos componentes. O AWS IoT Greengrass usa esse prefixo para os [componentes públicos](public-components.md) que ele fornece. Se você escolher o mesmo nome de um componente público, seu componente substituirá esse componente. Em seguida, AWS IoT Greengrass fornece seu componente em vez do componente público ao implantar componentes com dependência desse componente público. Esse atributo permite que você substitua o comportamento de componentes públicos, mas também pode interromper outros componentes se você não pretende substituir um público.
`ComponentVersion`
A versão do componente. O valor máximo para os valores principais, secundários e de patch é 999999.
AWS IoT Greengrass usa versões semânticas para componentes. As versões semânticas seguem um sistema de numeração *principal*.*secundária*.*patch*. Por exemplo, a versão `1.0.0` representa a primeira versão principal de um componente. Para mais informações, consulte a [especificação de versão semântica](https://semver.org/).
`ComponentDescription`
(Opcional) A descrição do componente.
`ComponentPublisher`
O publicador ou o autor do componente.
`ComponentConfiguration`
(Opcional) Um objeto que define a configuração ou os parâmetros do componente. Você define a configuração padrão e, ao implantar o componente, pode especificar o objeto de configuração a ser fornecido ao componente. A configuração do componente é compatível com parâmetros e estruturas aninhados. Esse objeto contém as informações a seguir:
`DefaultConfiguration`
Um objeto que define a configuração padrão para o componente. Você define a estrutura desse objeto.
AWS IoT Greengrass usa JSON para valores de configuração. O JSON especifica um tipo de número, mas não diferencia entre números inteiros e flutuantes. Como resultado, os valores de configuração podem ser convertidos em flutuantes no AWS IoT Greengrass. Para garantir que seu componente use o tipo de dados correto, recomendamos que você defina valores de configuração numéricos como strings. Em seguida, faça com que seu componente os analise como números inteiros ou flutuantes. Isso garante que seus valores de configuração tenham o mesmo tipo na configuração e no seu dispositivo principal.
`ComponentDependencies`
(Opcional) Um dicionário de objetos em que cada um define uma dependência de componente para o componente. A chave para cada objeto identifica o nome da dependência do componente. AWS IoT Greengrass instala dependências do componente quando o componente é instalado. AWS IoT Greengrass espera que as dependências comecem antes de iniciar o componente. Cada objeto contém as seguintes informações:
`VersionRequirement`
A restrição de versão semântica no estilo npm que define as versões de componentes compatíveis para essa dependência. É possível especificar uma versão ou um intervalo de versões. Para obter mais informações, consulte [calculadora de versão semântica npm](https://semver.npmjs.com/).
`DependencyType`
(Opcional) O tipo dessa dependência. Escolha entre as opções a seguir.
+ `SOFT` – O componente não é reiniciado se a dependência muda de estado.
+ `HARD` – O componente é reiniciado se a dependência muda de estado.
O padrão é `HARD`.
`ComponentType`
(Opcional) O tipo de componente.
Não recomendamos que você especifique o tipo de componente em uma receita. AWS IoT Greengrass define o tipo para você ao criar um componente.
O tipo pode ser um dos seguintes:
+ `aws.greengrass.generic`: o componente executa comandos ou fornece artefatos.
+ `aws.greengrass.lambda`: o componente executa uma função do Lambda usando o componente [componente do iniciador Lambda](lambda-launcher-component.md). O parâmetro `ComponentSource` especifica o ARN da função do Lambda que esse componente executa.
Não recomendamos que você use essa opção, pois ela é definida AWS IoT Greengrass quando você cria um componente a partir de uma função Lambda. Para obter mais informações, consulte [Executar funções AWS Lambda.](run-lambda-functions.md).
+ `aws.greengrass.plugin`: o componente é executado na mesma Java Virtual Machine (JVM) do Greengrass nucleus. Se você implantar ou reiniciar um componente de plug-in, o Greengrass nucleus será reiniciado.
Esse plug-in usa o mesmo arquivo de log do Greengrass nucleus. Para obter mais informações, consulte [Monitore AWS IoT Greengrass logs](monitor-logs.md).
Não recomendamos que você use essa opção em receitas de componentes, porque ela se destina a componentes AWS fornecidos escritos em Java que interagem diretamente com o núcleo do Greengrass. Para mais informações sobre quais componentes públicos são plug-ins, consulte [Componentes fornecidos pela AWS](public-components.md).
+ `aws.greengrass.nucleus`: o componente do núcleo. Para obter mais informações, consulte [Greengrass nucleus](greengrass-nucleus-component.md).
Não recomendamos que você use essa opção em fórmulas de componentes. Ela é destinada ao componente do Greengrass nucleus, que fornece a funcionalidade mínima do software AWS IoT Greengrass Core.
O padrão é `aws.greengrass.generic` quando você cria um componente a partir de uma fórmula ou `aws.greengrass.lambda` quando você cria um componente a partir de uma função do Lambda.
Para obter mais informações, consulte [Tipos de componentes](develop-greengrass-components.md#component-types).
`ComponentSource`
(Opcional) O ARN da função do Lambda que um componente executa.
Não recomendamos que você especifique a origem do componente em uma receita. AWS IoT Greengrass define esse parâmetro para você ao criar um componente a partir de uma função Lambda. Para obter mais informações, consulte [Executar funções AWS Lambda.](run-lambda-functions.md).
`Manifests`
Uma lista de objetos em que cada um define o ciclo de vida, os parâmetros e os requisitos do componente para uma plataforma. Se um dispositivo principal atender aos requisitos de plataforma de vários manifestos, AWS IoT Greengrass use o primeiro manifesto correspondente ao dispositivo principal. Para garantir que os dispositivos principais usem o manifesto correto, defina primeiro os manifestos com requisitos de plataforma mais rígidos. Um manifesto que se aplica a todas as plataformas deve ser o último manifesto na lista.
Um dispositivo principal deve atender aos requisitos de plataforma de pelo menos um manifesto para instalar o componente. Se nenhum manifesto corresponder ao dispositivo principal, o software AWS IoT Greengrass Core não instalará o componente e a implantação falhará.
Cada objeto contém as seguintes informações:
`Name`
(Opcional) Um nome fácil para a plataforma que esse manifesto define.
Se você omitir esse parâmetro, AWS IoT Greengrass cria um nome da plataforma `os` e. `architecture`
`Platform`
(Opcional) Um objeto que define a plataforma à qual esse manifesto se aplica. Omita esse parâmetro para definir um manifesto que se aplica a todas as plataformas.
Esse objeto especifica pares de valores-chave sobre a plataforma na qual um dispositivo principal é executado. Quando você implanta esse componente, o software AWS IoT Greengrass Core compara esses pares de valores-chave com os atributos da plataforma no dispositivo principal. O software AWS IoT Greengrass principal sempre define `os` e`architecture`, e pode definir atributos adicionais. É possível especificar atributos de plataforma personalizados para um dispositivo principal ao implantar o componente de Greengrass nucleus. Para obter mais informações, consulte o [parâmetro de substituição da plataforma](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides) do [componente de Greengrass nucleus](greengrass-nucleus-component.md).
Para cada par de chave-valor, é possível especificar um dos seguintes valores:
+ Um valor exato, como `linux` ou `windows`. Valores exatos devem começar com uma letra ou um número.
+ `*`, que corresponde a qualquer valor. Isso também corresponde quando um valor não está presente.
+ Uma expressão regular no estilo Java, como `/windows|linux/`. A expressão regular deve começar e terminar com um caractere de barra (`/`). Por exemplo, a expressão regular `/.+/` corresponde a qualquer valor que não esteja em branco.
Esse objeto contém as informações a seguir:
`runtime`
O [runtime do Greengrass nucleus](https://docs.aws.amazon.com/greengrass/v2/developerguide/how-it-works.html#concept-overview) para a plataforma que esse manifesto oferece suporte. Ao definir vários manifestos com `runtime` de plataforma, os valores de runtime com suporte em uma receita são `aws_nucleus_lite` e `*` somente. Para atingir um dispositivo classic, o campo de runtime NÃO DEVE ser especificado na receita. Os runtimes do Greengrass Nucleus com suporte incluem os seguintes valores:
+ `*`
+ `aws_nucleus_lite`
`os`
(Opcional) O nome do sistema operacional da plataforma compatível com esse manifesto. Plataformas comuns incluem os seguintes valores:
+ `linux`
+ `windows`
+ `darwin` (macOS)
`architecture`
(Opcional) A arquitetura do processador para a plataforma compatível com esse manifesto. Arquiteturas comuns incluem os seguintes valores:
+ `amd64`
+ `arm`
+ `aarch64`
+ `x86`
`architecture.detail`
(Opcional) O detalhe da arquitetura do processador para a plataforma compatível com esse manifesto. Detalhes comuns de arquitetura incluem os seguintes valores:
+ `arm61`
+ `arm71`
+ `arm81`
`key`
(Opcional) Um atributo de plataforma que você define para esse manifesto. *Key*Substitua pelo nome do atributo da plataforma. O software AWS IoT Greengrass Core combina esse atributo da plataforma com os pares de valores-chave que você especifica na configuração do componente nuclear do Greengrass. Para obter mais informações, consulte o [parâmetro de substituição da plataforma](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides) do [componente de Greengrass nucleus](greengrass-nucleus-component.md).
Use o formato de nome de domínio inverso para evitar colisões de nomes dentro da empresa. Por exemplo, se sua empresa é dona do `example.com` e você trabalha em um projeto de rádio, é possível nomear um atributo de plataforma personalizado como `com.example.radio.RadioModule`. Isso ajuda a evitar colisões de nomes de atributos de plataforma dentro da sua empresa.
Por exemplo, é possível definir um atributo de plataforma, `com.example.radio.RadioModule`, para especificar um manifesto diferente com base em qual módulo de rádio está disponível em um dispositivo principal. Cada manifesto pode incluir artefatos diferentes que se aplicam a diferentes configurações de hardware, para que você implante o conjunto mínimo de software no dispositivo principal.
`Lifecycle`
Um objeto ou string que define como instalar e executar o componente na plataforma definida por esse manifesto. Também é possível definir um [ciclo de vida global](#global-lifecycle-definition) que se aplique a todas as plataformas. O dispositivo principal usa o ciclo de vida global somente se o manifesto a ser usado não especificar um ciclo de vida.
Você define esse ciclo de vida em um manifesto. As etapas do ciclo de vida que você especifica aqui se aplicam somente à plataforma definida por esse manifesto. Também é possível definir um [ciclo de vida global](#global-lifecycle-definition) que se aplique a todas as plataformas.
Este objeto ou string contém as seguintes informações:
`Setenv`
(Opcional) Um dicionário de variáveis de ambiente para fornecer a todos os scripts de ciclo de vida. É possível substituir essas variáveis de ambiente com `Setenv` em cada script de ciclo de vida.
`install`
(Opcional) Um objeto ou string que define o script a ser executado quando o componente é instalado. O software AWS IoT Greengrass principal também executa essa etapa do ciclo de vida toda vez que o software é lançado.
Se o script `install` sair com um código de sucesso, o componente entrará no estado `INSTALLED`.
Este objeto ou string contém as seguintes informações:
`Script`
O script a ser executado.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Skipif`
(Opcional) A verificação para determinar se o script deve ou não ser executado. É possível definir para verificar se um executável está no caminho ou se existe um arquivo. Se a saída for verdadeira, o software AWS IoT Greengrass Core pulará a etapa. Escolha uma das seguintes verificações:
+ `onpath runnable`: verifique se um executável está no caminho do sistema. Por exemplo, use **onpath python3** para pular essa etapa do ciclo de vida se o Python 3 estiver disponível.
+ `exists file`: verifique se existe um arquivo. Por exemplo, use **exists /tmp/my-configuration.db** para pular essa etapa do ciclo de vida, se `/tmp/my-configuration.db` estiver presente.
`Timeout`
(Opcional) O tempo máximo, em segundos, em que o script pode ser executado antes que o software AWS IoT Greengrass Core termine o processo.
Padrão: 120 segundos
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`run`
(Opcional) Um objeto ou string que define o script a ser executado quando o componente é iniciado.
O componente entra no estado `RUNNING` em que essa etapa do ciclo de vida é executada. Se o script `run` sair com um código de sucesso, o componente entrará no estado `STOPPING`. Se um script `shutdown` for especificado, ele será executado; caso contrário, o componente entrará no estado `FINISHED`.
Os componentes que dependem desse componente são iniciados quando essa etapa do ciclo de vida é executada. Para executar um processo em segundo plano, como um serviço usado por componentes dependentes, use a etapa `startup` do ciclo de vida.
Quando você implanta componentes com um ciclo de vida `run`, o dispositivo principal pode relatar a implantação como concluída assim que esse script de ciclo de vida é executado. Como resultado, a implantação pode ser concluída e bem-sucedida mesmo se o script `run` do ciclo de vida falhar logo após a execução. Se você quiser que o status de implantação dependa do resultado do script de inicialização do componente, use a etapa `startup` do ciclo de vida em vez disso.
É possível definir somente um ciclo de vida `startup` ou `run`.
Este objeto ou string contém as seguintes informações:
`Script`
O script a ser executado.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Skipif`
(Opcional) A verificação para determinar se o script deve ou não ser executado. É possível definir para verificar se um executável está no caminho ou se existe um arquivo. Se a saída for verdadeira, o software AWS IoT Greengrass Core pulará a etapa. Escolha uma das seguintes verificações:
+ `onpath runnable`: verifique se um executável está no caminho do sistema. Por exemplo, use **onpath python3** para pular essa etapa do ciclo de vida se o Python 3 estiver disponível.
+ `exists file`: verifique se existe um arquivo. Por exemplo, use **exists /tmp/my-configuration.db** para pular essa etapa do ciclo de vida, se `/tmp/my-configuration.db` estiver presente.
`Timeout`
(Opcional) O tempo máximo em segundos que o script pode ser executado antes que o software AWS IoT Greengrass principal encerre o processo.
Por padrão, essa etapa do ciclo de vida não atinge o tempo limite. Se você omitir esse tempo limite, o script `run` será executado até ser encerrado.
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`startup`
(Opcional) Um objeto ou string que define o processo em segundo plano a ser executado quando o componente é iniciado.
Use `startup` para executar um comando que deve sair com êxito ou atualizar o status do componente para `RUNNING` antes que os componentes dependentes possam ser iniciados. Use a operação [UpdateState](ipc-component-lifecycle.md#ipc-operation-updatestate)IPC para definir o status do componente como `RUNNING` ou `ERRORED` quando o componente inicia um script que não sai. Por exemplo, é possível definir uma etapa `startup` que inicie o processo do MySQL com `/etc/init.d/mysqld start`.
O componente entra no estado `STARTING` em que essa etapa do ciclo de vida é executada. Se o script `startup` sair com um código de sucesso, o componente entrará no estado `RUNNING`. Em seguida, os componentes dependentes podem ser iniciados.
Quando você implanta componentes com um ciclo de vida `startup`, o dispositivo principal pode relatar a implantação como concluída assim que esse script de ciclo de vida sai ou relata o estado. Em outras palavras, o status da implantação é `IN_PROGRESS` até que os scripts de inicialização de todos os componentes saiam ou relatem um estado.
É possível definir somente um ciclo de vida `startup` ou `run`.
Este objeto ou string contém as seguintes informações:
`Script`
O script a ser executado.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Skipif`
(Opcional) A verificação para determinar se o script deve ou não ser executado. É possível definir para verificar se um executável está no caminho ou se existe um arquivo. Se a saída for verdadeira, o software AWS IoT Greengrass Core pulará a etapa. Escolha uma das seguintes verificações:
+ `onpath runnable`: verifique se um executável está no caminho do sistema. Por exemplo, use **onpath python3** para pular essa etapa do ciclo de vida se o Python 3 estiver disponível.
+ `exists file`: verifique se existe um arquivo. Por exemplo, use **exists /tmp/my-configuration.db** para pular essa etapa do ciclo de vida, se `/tmp/my-configuration.db` estiver presente.
`Timeout`
(Opcional) O tempo máximo, em segundos, em que o script pode ser executado antes que o software AWS IoT Greengrass Core termine o processo.
Padrão: 120 segundos
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`shutdown`
(Opcional) Um objeto ou string que define o script a ser executado quando o componente é encerrado. Use o ciclo de vida de desligamento para executar o código que você quer executar quando o componente estiver no estado `STOPPING`. O ciclo de vida de desligamento pode ser usado para interromper um processo iniciado pelos scripts `startup` ou `run`.
Se você iniciar um processo em segundo plano na `startup`, use a etapa `shutdown` para interromper esse processo quando o componente for encerrado. Por exemplo, é possível definir uma etapa `shutdown` que pare o processo do MySQL com `/etc/init.d/mysqld stop`.
O script `shutdown` é executado depois que o componente entra no estado `STOPPING`. Se o script for concluído com êxito, o componente entrará no estado `FINISHED`.
Este objeto ou string contém as seguintes informações:
`Script`
O script a ser executado.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Skipif`
(Opcional) A verificação para determinar se o script deve ou não ser executado. É possível definir para verificar se um executável está no caminho ou se existe um arquivo. Se a saída for verdadeira, o software AWS IoT Greengrass Core pulará a etapa. Escolha uma das seguintes verificações:
+ `onpath runnable`: verifique se um executável está no caminho do sistema. Por exemplo, use **onpath python3** para pular essa etapa do ciclo de vida se o Python 3 estiver disponível.
+ `exists file`: verifique se existe um arquivo. Por exemplo, use **exists /tmp/my-configuration.db** para pular essa etapa do ciclo de vida, se `/tmp/my-configuration.db` estiver presente.
`Timeout`
(Opcional) O tempo máximo em segundos que o script pode ser executado antes que o software AWS IoT Greengrass principal encerre o processo.
Padrão: 15 segundos.
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`recover`
(Opcional) Um objeto ou string que define o script a ser executado quando o componente encontra um erro.
Esta etapa é executada quando um componente entra no estado `ERRORED`. Se o componente se tornar `ERRORED` três vezes sem se recuperar com sucesso, ele mudará para o estado `BROKEN`. Para corrigir um componente `BROKEN`, é preciso implantá-lo novamente.
Este objeto ou string contém as seguintes informações:
`Script`
O script a ser executado.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Skipif`
(Opcional) A verificação para determinar se o script deve ou não ser executado. É possível definir para verificar se um executável está no caminho ou se existe um arquivo. Se a saída for verdadeira, o software AWS IoT Greengrass Core pulará a etapa. Escolha uma das seguintes verificações:
+ `onpath runnable`: verifique se um executável está no caminho do sistema. Por exemplo, use **onpath python3** para pular essa etapa do ciclo de vida se o Python 3 estiver disponível.
+ `exists file`: verifique se existe um arquivo. Por exemplo, use **exists /tmp/my-configuration.db** para pular essa etapa do ciclo de vida, se `/tmp/my-configuration.db` estiver presente.
`Timeout`
(Opcional) O tempo máximo em segundos que o script pode ser executado antes que o software AWS IoT Greengrass principal encerre o processo.
Padrão: 60 segundos.
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`bootstrap`
(Opcional) Um objeto ou string que define um script que exige que o software AWS IoT Greengrass Core ou o dispositivo principal seja reiniciado. Isso permite desenvolver um componente que executa uma reinicialização após instalar atualizações do sistema operacional ou atualizações de runtime, por exemplo.
Para instalar atualizações ou dependências que não exijam a reinicialização do software ou dispositivo AWS IoT Greengrass Core, use o ciclo de [vida da instalação](#install-lifecycle-definition).
Essa etapa do ciclo de vida é executada antes da etapa do ciclo de vida da instalação nos seguintes casos, quando o software AWS IoT Greengrass principal implanta o componente:
+ O componente é implantado no dispositivo principal pela primeira vez.
+ A versão do componente altera.
+ O script de bootstrap muda como resultado de uma atualização da configuração do componente.
Depois que o software AWS IoT Greengrass principal concluir a etapa de inicialização de todos os componentes que têm uma etapa de inicialização em uma implantação, o software é reiniciado.
Você deve configurar o software AWS IoT Greengrass Core como um serviço do sistema para reiniciar o software AWS IoT Greengrass Core ou o dispositivo principal. Se você não configurar o software AWS IoT Greengrass Core como um serviço do sistema, o software não será reiniciado. Para obter mais informações, consulte [Configurar o Greengrass nucleus como um serviço do sistema](configure-greengrass-core-v2.md#configure-system-service).
Este objeto ou string contém as seguintes informações:
`BootstrapOnRollback`
Quando esse recurso estiver ativado, o `BootstrapOnRollback` será executado somente para componentes que concluíram ou tentaram executar as etapas do ciclo de vida do bootstrap como parte de uma implantação de destino com falha. Esse atributo está disponível com o Greengrass nucleus versão 2.12.0 e posteriores.
(Opcional) É possível executar as etapas do ciclo de vida do bootstrap como parte de uma implantação de reversão. Se você definir essa opção como `true`, as etapas do ciclo de vida do bootstrap definidas em uma implantação de reversão serão executadas. Quando uma implantação falha, a versão anterior do ciclo de vida de bootstrap do componente será executada novamente durante uma implantação de reversão.
O padrão é `false`.
`Script`
O script a ser executado. O código de saída desse script define a instrução de reinicialização. Use os seguintes códigos de saída:
+ `0`— Não reinicie o software AWS IoT Greengrass principal nem o dispositivo principal. O software AWS IoT Greengrass Core ainda reinicia após a inicialização de todos os componentes.
+ `100`— Solicitação para reiniciar o software AWS IoT Greengrass principal.
+ `101`: solicitação para reiniciar o dispositivo principal.
Os códigos de saída de 100 a 199 são reservados para comportamentos especiais. Outros códigos de saída representam erros de script.
`RequiresPrivilege`
(Opcional) É possível executar o script com privilégios de raiz. Se você definir essa opção como`true`, o software AWS IoT Greengrass Core executará esse script de ciclo de vida como root em vez de como usuário do sistema que você configura para executar esse componente. O padrão é `false`.
`Timeout`
(Opcional) O tempo máximo, em segundos, em que o script pode ser executado antes que o software AWS IoT Greengrass Core termine o processo.
Padrão: 120 segundos
`Setenv`
(Opcional) O dicionário de variáveis de ambiente a serem fornecidas ao script. Essas variáveis de ambiente substituem as variáveis que você fornece em `Lifecycle.Setenv`.
`Selections`
(Opcional) Uma lista de chaves de seleção que especificam seções do [ciclo de vida global](#global-lifecycle-definition) a serem executadas para esse manifesto. No ciclo de vida global, é possível definir etapas do ciclo de vida com chaves de seleção em qualquer nível para selecionar subseções do ciclo de vida. Em seguida, o dispositivo principal usa as seções que correspondem às teclas de seleção nesse manifesto. Para mais informações, consulte os [exemplos de ciclo de vida global](#global-lifecycle-definition).
O dispositivo principal usa as seleções do ciclo de vida global somente se este manifesto não definir um ciclo de vida.
É possível especificar a chave de seleção `all` para executar seções do ciclo de vida global que não têm chaves de seleção.
`Artifacts`
(Opcional) Uma lista de objetos, cada um definindo um artefato binário para o componente na plataforma definido por esse manifesto. Por exemplo, é possível definir código ou imagens como artefatos.
Quando o componente é implantado, o software AWS IoT Greengrass Core baixa o artefato em uma pasta no dispositivo principal. Você também pode definir artefatos como arquivos que o software extrai após baixá-los.
É possível usar [variáveis de fórmula](#recipe-variables) para obter os caminhos para as pastas em que os artefatos são instalados no dispositivo principal.
+ Arquivos normais: use a [variável de fórmula artifacts:path](#component-recipe-artifacts-path) para obter o caminho para a pasta que contém os artefatos. Por exemplo, especifique `{artifacts:path}/my_script.py` em uma fórmula para obter o caminho para um artefato que tenha o URI `s3://amzn-s3-demo-bucket/path/to/my_script.py`.
+ Arquivos extraídos: use a [variável de fórmula artifacts:DecompressedPath](#component-recipe-artifacts-decompressed-path) para obter o caminho para a pasta que contém os artefatos do arquivo extraído. O software AWS IoT Greengrass Core extrai cada arquivo em uma pasta com o mesmo nome do arquivo. Por exemplo, especifique `{artifacts:decompressedPath}/my_archive/my_script.py` em uma fórmula para obter o caminho para `my_script.py` no artefato de arquivo que tenha o URI `s3://amzn-s3-demo-bucket/path/to/my_archive.zip`.
Ao desenvolver um componente com um artefato de arquivo em um dispositivo principal local, talvez você não tenha um URI para esse artefato. Para testar seu componente com uma opção `Unarchive` que extrai o artefato, especifique um URI em que o nome do arquivo corresponda ao nome do arquivo do artefato de arquivo. É possível especificar o URI no qual você espera carregar o artefato de arquivo ou pode especificar um novo URI de espaço reservado. Por exemplo, para extrair o artefato `my_archive.zip` durante uma implantação local, é possível especificar `s3://amzn-s3-demo-bucket/my_archive.zip`.
Cada objeto contém as seguintes informações:
`Uri`
O URI de um artefato em um bucket do S3. O software AWS IoT Greengrass Core busca o artefato desse URI quando o componente é instalado, a menos que o artefato já exista no dispositivo. Cada artefato deve ter um nome de arquivo exclusivo em cada manifesto.
`Unarchive`
(Opcional) O tipo de arquivo a ser descompactado. Escolha uma das seguintes opções:
+ `NONE`: o arquivo não é um arquivo para descompactar. O software AWS IoT Greengrass Core instala o artefato em uma pasta no dispositivo principal. É possível usar a [variável de fórmula artifacts:path](#component-recipe-artifacts-path) para obter o caminho para essa pasta.
+ `ZIP`: o arquivo é um arquivo ZIP. O software AWS IoT Greengrass Core extrai o arquivo em uma pasta com o mesmo nome do arquivo. É possível usar a [variável de fórmula artifacts:decompressedPath](#component-recipe-artifacts-decompressed-path) para obter o caminho para a pasta que contém esta pasta.
O padrão é `NONE`.
`Permission`
(Opcional) Um objeto que define as permissões de acesso a serem definidas para esse arquivo de artefato. É possível definir a permissão de leitura e a permissão de execução.
Você não pode definir a permissão de gravação, porque o software AWS IoT Greengrass Core não permite que os componentes editem arquivos de artefatos na pasta de artefatos. Para editar um arquivo de artefato em um componente, copie-o para outro local ou publique e implante um novo arquivo de artefato.
Se você definir um artefato como um arquivo a ser descompactado, o software AWS IoT Greengrass Core definirá essas permissões de acesso nos arquivos que ele descompacta do arquivamento. O software AWS IoT Greengrass Core define as permissões de acesso da pasta `ALL` para `Read` `Execute` e. Isso permite que os componentes visualizem os arquivos descompactados na pasta. Para definir permissões em arquivos individuais do arquivo, você pode definir as permissões no script do [ciclo de vida da instalação](#install-lifecycle-definition).
Esse objeto contém as informações a seguir:
`Read`
(Opcional) A permissão de leitura a ser definida para esse arquivo de artefato. Para permitir que outros componentes acessem esse artefato, como componentes que dependem dele, especifique `ALL`. Escolha uma das seguintes opções:
+ `NONE`: o arquivo não está legível.
+ `OWNER`: o arquivo pode ser lido pelo usuário do sistema que você configura para executar esse componente.
+ `ALL`: o arquivo pode ser lido por todos os usuários.
O padrão é `OWNER`.
`Execute`
(Opcional) A permissão de execução a ser definida para esse arquivo de artefato. A permissão `Execute` implica a permissão `Read`. Por exemplo, se você especificar `ALL` para `Execute`, todos os usuários poderão ler e executar esse arquivo de artefato.
Escolha uma das seguintes opções:
+ `NONE`: o arquivo não pode ser executado.
+ `OWNER`: o arquivo pode ser executado pelo usuário do sistema que você configura para executar o componente.
+ `ALL`: o arquivo pode ser executado por todos os usuários.
O padrão é `NONE`.
`Digest`
(Somente leitura) O hash criptográfico do resumo do artefato. Quando você cria um componente, AWS IoT Greengrass usa um algoritmo de hash para calcular um hash do arquivo de artefato. Então, quando você implanta o componente, o Greengrass nucleus calcula o hash do artefato baixado e compara o hash com esse resumo para verificar o artefato antes da instalação. Se o hash não corresponder ao resumo, a implantação falhará.
Se você definir esse parâmetro, AWS IoT Greengrass substituirá o valor definido ao criar o componente.
`Algorithm`
(Somente leitura) O algoritmo de hash AWS IoT Greengrass usado para calcular o hash de resumo do artefato.
Se você definir esse parâmetro, AWS IoT Greengrass substituirá o valor definido ao criar o componente.
`Lifecycle`
Um objeto que define como instalar e executar o componente. O dispositivo principal usa o ciclo de vida global somente se o [manifesto](#manifest-definition) a ser usado não especifica um ciclo de vida.
Você define esse ciclo de vida dentro de um manifesto. Você também pode definir um [ciclo de vida do manifesto](#manifest-lifecycle-definition) que se aplica às plataformas que correspondem a ele.
No ciclo de vida global, você pode especificar ciclos de vida que são executados para determinadas [chaves de seleção](#manifest-selections-definition) que você especifica em cada manifesto. As chaves de seleção são cadeias de caracteres que identificam seções do ciclo de vida global a serem executadas para cada manifesto.
A tecla de seleção `all` é o padrão em qualquer seção sem uma chave de seleção. Isso significa que você pode especificar a chave de seleção `all` em um manifesto para executar as seções do ciclo de vida global sem chaves de seleção. Não é necessário especificar a chave de seleção `all` no ciclo de vida global.
Se um manifesto não definir um ciclo de vida ou chaves de seleção, o dispositivo principal usará a seleção `all` como padrão. Isso significa que, nesse caso, o dispositivo principal usa as seções do ciclo de vida global que não usam teclas de seleção.
Esse objeto contém as mesmas informações do [ciclo de vida do manifesto](#manifest-lifecycle-definition), mas você pode especificar chaves de seleção em qualquer nível para selecionar subseções do ciclo de vida.
Recomendamos que você use somente letras minúsculas para cada chave de seleção para evitar conflitos entre as chaves de seleção e as chaves do ciclo de vida. As chaves de ciclo de vida começam com uma letra maiúscula.
**Example Exemplo de ciclo de vida global com chaves de seleção de alto nível**
```
Lifecycle:
key1:
install:
SkipIf: either onpath executable or exists file
Script: command1
key2:
install:
Script: command2
all:
install:
Script: command3
```
**Example Exemplo de ciclo de vida global com chaves de seleção de nível inferior**
```
Lifecycle:
install:
Script:
key1: command1
key2: command2
all: command3
```
**Example Exemplo de ciclo de vida global com chaves de seleção de vários níveis**
```
Lifecycle:
key1:
install:
SkipIf: either onpath executable or exists file
Script: command1
key2:
install:
Script: command2
all:
install:
Script:
key3: command3
key4: command4
all: command5
```
## Variáveis da fórmula
As variáveis da fórmula expõem informações do componente e do núcleo atuais para você usar nas fórmulas. Por exemplo, você pode usar uma variável de fórmula para passar parâmetros de configuração do componente para uma aplicação executada em um script de ciclo de vida.
É possível usar variáveis de fórmula nas seguintes seções das fórmulas de componentes:
+ Definições do ciclo de vida.
+ Definições de configuração de componentes, se você usar o [Greengrass nucleus](greengrass-nucleus-component.md) v2.6.0 ou posterior e definir a opção de configuração como. [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)`true` Você também pode usar variáveis de fórmulas ao [implantar atualizações de configuração de componentes](update-component-configurations.md#merge-configuration-update-recipe-variables).
As variáveis da fórmula usam a sintaxe `{recipe_variable}`. Os colchetes indicam uma variável de fórmula.
AWS IoT Greengrass suporta as seguintes variáveis de receita:
`component_dependency_name:configuration:json_pointer`
O valor de um parâmetro de configuração para o componente que essa fórmula define ou para um componente do qual esse componente depende.
É possível usar essa variável para fornecer um parâmetro para um script executado no ciclo de vida do componente.
AWS IoT Greengrass suporta essa variável de receita somente nas definições do ciclo de vida do componente.
Essa variável de fórmula tem as seguintes entradas:
+ `component_dependency_name`: (opcional) o nome da dependência do componente para consultar. Omita esse segmento para consultar o componente definido por essa fórmula. É possível especificar apenas dependências diretas.
+ `json_pointer`: o ponteiro JSON para o valor da configuração a ser avaliado. Os ponteiros JSON começam com uma barra `/`. Para identificar um valor em uma configuração de componente aninhado, use barras (`/`) para separar as chaves de cada nível na configuração. É possível usar um número como chave para especificar um índice em uma lista. Para obter mais informações, consulte a [Especificação do ponteiro JSON](https://tools.ietf.org/html/rfc6901).
AWS IoT Greengrass O Core usa ponteiros JSON para receitas no formato YAML.
O ponteiro JSON pode fazer referência aos seguintes tipos de nós:
+ Um nó de valor. AWS IoT Greengrass O Core substitui a variável da receita pela representação em cadeia do valor. Valores nulos são convertidos como `null` em uma string.
+ Um nó de objeto. AWS IoT Greengrass O Core substitui a variável de receita pela representação serializada da string JSON desse objeto.
+ Sem nó. AWS IoT Greengrass O núcleo não substitui a variável da receita.
Por exemplo, a variável da fórmula `{configuration:/Message}` recupera o valor da chave `Message` na configuração do componente. A variável de fórmula `{com.example.MyComponentDependency:configuration:/server/port}` recupera o valor de `port` no objeto de configuração `server` de uma dependência de componente.
`component_dependency_name:artifacts:path`
O caminho raiz dos artefatos para o componente que esta fórmula define ou para um componente do qual este componente depende.
Quando um componente é instalado, AWS IoT Greengrass copia os artefatos do componente para a pasta que essa variável expõe. É possível usar essa variável para identificar a localização de um script a ser executado no ciclo de vida do componente, por exemplo.
A pasta nesse caminho é somente para leitura. Para modificar arquivos de artefatos, copie os arquivos para outro local, como o diretório de trabalho atual (`$PWD` ou `.`). Em seguida, modifique os arquivos ali.
Para ler ou executar um artefato a partir de uma dependência de componente, essa permissão `Read` ou `Execute` do artefato deve ser `ALL`. Para mais informações, consulte as [permissões de artefato](#component-artifact-permission) que você define na fórmula do componente.
Essa variável de fórmula tem as seguintes entradas:
+ `component_dependency_name`: (opcional) o nome da dependência do componente para consultar. Omita esse segmento para consultar o componente definido por essa fórmula. É possível especificar apenas dependências diretas.
`component_dependency_name:artifacts:decompressedPath`
O caminho raiz dos artefatos de arquivo descompactado para o componente que essa fórmula define ou para um componente do qual ele depende.
Quando um componente é instalado, AWS IoT Greengrass descompacta os artefatos de arquivamento do componente na pasta que essa variável expõe. É possível usar essa variável para identificar a localização de um script a ser executado no ciclo de vida do componente, por exemplo.
Cada artefato é descompactado em uma pasta dentro do caminho descompactado, em que a pasta tem o mesmo nome do artefato menos a extensão dele. Por exemplo, um artefato ZIP chamado `models.zip` descompacta na pasta `{artifacts:decompressedPath}/models`.
A pasta nesse caminho é somente para leitura. Para modificar arquivos de artefatos, copie os arquivos para outro local, como o diretório de trabalho atual (`$PWD` ou `.`). Em seguida, modifique os arquivos ali.
Para ler ou executar um artefato a partir de uma dependência de componente, essa permissão `Read` ou `Execute` do artefato deve ser `ALL`. Para mais informações, consulte as [permissões de artefato](#component-artifact-permission) que você define na fórmula do componente.
Essa variável de fórmula tem as seguintes entradas:
+ `component_dependency_name`: (opcional) o nome da dependência do componente para consultar. Omita esse segmento para consultar o componente definido por essa fórmula. É possível especificar apenas dependências diretas.
`component_dependency_name:work:path`
Esse recurso está disponível para a versão 2.0.4 e posteriores do [componente de Greengrass nucleus](greengrass-nucleus-component.md).
O caminho de trabalho para o componente que esta fórmula define ou para um componente do qual este componente depende. O valor dessa variável de fórmula é equivalente à saída da variável de ambiente `$PWD` e do comando [pwd](https://en.wikipedia.org/wiki/Pwd) quando executado a partir do contexto do componente.
É possível usar essa variável de fórmula para compartilhar arquivos entre um componente e uma dependência.
A pasta nesse caminho pode ser lida e gravada pelo componente definido por essa fórmula e por outros componentes que são executados pelo mesmo usuário e grupo.
Essa variável de fórmula tem as seguintes entradas:
+ `component_dependency_name`: (opcional) o nome da dependência do componente para consultar. Omita esse segmento para consultar o componente definido por essa fórmula. É possível especificar apenas dependências diretas.
`kernel:rootPath`
O caminho raiz AWS IoT Greengrass principal.
`iot:thingName`
Esse recurso está disponível para a versão 2.3.0 e posteriores do [componente de Greengrass nucleus](greengrass-nucleus-component.md).
O nome do dispositivo AWS IoT principal.
## Exemplos de fórmula
É possível consultar os seguintes exemplos de fórmulas para ajudar a criar fórmulas para seus componentes.
AWS IoT Greengrass organiza um índice dos componentes do Greengrass, chamado Catálogo de Software do Greengrass. Este catálogo rastreia os componentes do Greengrass que são desenvolvidos pela comunidade do Greengrass. A partir desse catálogo, você pode baixar, modificar e implantar componentes para criar suas aplicações Greengrass. Para obter mais informações, consulte [Componentes da comunidade](greengrass-software-catalog.md).
**Topics**
+ [Fórmula do componente do Hello World](#recipe-example-hello-world)
+ [Exemplo de componente do runtime do Python](#recipe-example-python-runtime)
+ [Fórmula de componente que especifica vários campos](#recipe-example-all-fields)
### Fórmula do componente do Hello World
A fórmula a seguir descreve um componente Hello World que executa um script do Python. Esse componente é compatível com todas as plataformas e aceita um parâmetro `Message` que o AWS IoT Greengrass passa como argumento para o script Python. Esta é a fórmula do componente Hello World no [tutorial de introdução](getting-started.md).
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
```
------
### Exemplo de componente do runtime do Python
A fórmula a seguir descreve um componente que instala o Python. Esse componente é compatível com dispositivos Linux de 64 bits.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PythonRuntime",
"ComponentDescription": "Installs Python 3.7",
"ComponentPublisher": "Amazon",
"ComponentVersion": "3.7.0",
"Manifests": [
{
"Platform": {
"os": "linux",
"architecture": "amd64"
},
"Lifecycle": {
"install": "apt-get update\napt-get install python3.7"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PythonRuntime
ComponentDescription: Installs Python 3.7
ComponentPublisher: Amazon
ComponentVersion: '3.7.0'
Manifests:
- Platform:
os: linux
architecture: amd64
Lifecycle:
install: |
apt-get update
apt-get install python3.7
```
------
### Fórmula de componente que especifica vários campos
A fórmula do componente a seguir usa vários campos de fórmula.
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.FooService",
"ComponentDescription": "Complete recipe for AWS IoT Greengrass components",
"ComponentPublisher": "Amazon",
"ComponentVersion": "1.0.0",
"ComponentConfiguration": {
"DefaultConfiguration": {
"TestParam": "TestValue"
}
},
"ComponentDependencies": {
"BarService": {
"VersionRequirement": "^1.1.0",
"DependencyType": "SOFT"
},
"BazService": {
"VersionRequirement": "^2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "linux",
"architecture": "amd64"
},
"Lifecycle": {
"install": {
"Skipif": "onpath git",
"Script": "sudo apt-get install git"
},
"Setenv": {
"environment_variable1": "variable_value1",
"environment_variable2": "variable_value2"
}
},
"Artifacts": [
{
"Uri": "s3://amzn-s3-demo-bucket/hello_world.zip",
"Unarchive": "ZIP"
},
{
"Uri": "s3://amzn-s3-demo-bucket/hello_world_linux.py"
}
]
},
{
"Lifecycle": {
"install": {
"Skipif": "onpath git",
"Script": "sudo apt-get install git",
"RequiresPrivilege": "true"
}
},
"Artifacts": [
{
"Uri": "s3://amzn-s3-demo-bucket/hello_world.py"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.FooService
ComponentDescription: Complete recipe for AWS IoT Greengrass components
ComponentPublisher: Amazon
ComponentVersion: 1.0.0
ComponentConfiguration:
DefaultConfiguration:
TestParam: TestValue
ComponentDependencies:
BarService:
VersionRequirement: ^1.1.0
DependencyType: SOFT
BazService:
VersionRequirement: ^2.0.0
Manifests:
- Platform:
os: linux
architecture: amd64
Lifecycle:
install:
SkipIf: onpath git
Script: sudo apt-get install git
SetEnv:
environment_variable1: variable_value1
environment_variable2: variable_value2
Artifacts:
- Uri: 's3://amzn-s3-demo-bucket/hello_world.zip'
Unarchive: ZIP
- Uri: 's3://amzn-s3-demo-bucket/hello_world_linux.py'
- Lifecycle:
install:
SkipIf: onpath git
Script: sudo apt-get install git
RequiresPrivilege: 'true'
Artifacts:
- Uri: 's3://amzn-s3-demo-bucket/hello_world.py'
```
------
# Referência de variável de ambiente do componente
O software AWS IoT Greengrass Core define variáveis de ambiente quando executa scripts de ciclo de vida para componentes. Você pode obter essas variáveis de ambiente em seus componentes para obter o nome da coisa e a Região da AWS versão do núcleo do Greengrass. O software também define as variáveis de ambiente que seu componente exige para usar o [SDK de comunicação entre processos](interprocess-communication.md) e para [interagir com os serviços da AWS](interact-with-aws-services.md).
Também é possível definir variáveis de ambiente personalizadas para os scripts de ciclo de vida do seu componente. Para obter mais informações, consulte [Setenv](component-recipe-reference.md#lifecycle-setenv-definition).
O software AWS IoT Greengrass Core define as seguintes variáveis de ambiente:
`AWS_IOT_THING_NAME`
O nome da AWS IoT coisa que representa esse dispositivo principal do Greengrass.
`AWS_REGION`
Região da AWS Onde esse dispositivo principal do Greengrass opera.
AWS SDKs Use essa variável de ambiente para identificar a região padrão a ser usada. Essa variável é equivalente a `AWS_DEFAULT_REGION`.
`AWS_DEFAULT_REGION`
Região da AWS Onde esse dispositivo principal do Greengrass opera.
O AWS CLI usa essa variável de ambiente para identificar a região padrão a ser usada. Essa variável é equivalente a `AWS_REGION`.
`GGC_VERSION`
A versão do [componente do núcleo do Greengrass](greengrass-nucleus-component.md) que é executada nesse dispositivo principal do Greengrass.
`GG_ROOT_CA_PATH`
Esse atributo está disponível para a versão 2.5.5 e posteriores do [componente de núcleo do Greengrass](greengrass-nucleus-component.md).
O caminho para o certificado de (CA) raiz que o núcleo do Greengrass usa.
`AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT`
O caminho para o soquete IPC que os componentes usam para se comunicar com o software AWS IoT Greengrass Core. Para obter mais informações, consulte [Use o AWS IoT Device SDK para se comunicar com o núcleo do Greengrass, outros componentes e AWS IoT CoreComunique-se com o núcleo do Greengrass, outros componentes e AWS IoT Core](interprocess-communication.md).
`SVCUID`
O token secreto que os componentes usam para se conectar ao soquete IPC e se comunicar com o software AWS IoT Greengrass Core. Para obter mais informações, consulte [Use o AWS IoT Device SDK para se comunicar com o núcleo do Greengrass, outros componentes e AWS IoT CoreComunique-se com o núcleo do Greengrass, outros componentes e AWS IoT Core](interprocess-communication.md).
`AWS_CONTAINER_AUTHORIZATION_TOKEN`
O token secreto que os componentes usam para recuperar credenciais do [componente do serviço de troca de tokens](token-exchange-service-component.md).
`AWS_CONTAINER_CREDENTIALS_FULL_URI`
O URI que os componentes solicitam para recuperar credenciais do [componente do serviço de troca de tokens](token-exchange-service-component.md).