Usar o esquema JSON do Workflows no seu ambiente de desenvolvimento integrado

Para fornecer suporte à sintaxe ao criar um fluxo de trabalho, use o esquema JSON de fluxos de trabalho em um ambiente de desenvolvimento integrado (IDE), como o Visual Studio Code (VS Code) ou o Intellij IDEA. O suporte à sintaxe inclui preenchimento automático, validação e documentação inline. O esquema também pode ser integrado aos seus processos de CI/CD.

O esquema JSON dos fluxos de trabalho é escrito em JSON Schema, uma linguagem declarativa que permite anotar e validar documentos JSON. A origem do esquema está hospedada em SchemaStore.org, um repositório de esquemas para arquivos de configuração comuns baseados em JSON. Os esquemas do SchemaStore.org também podem ser aplicados a arquivos YAML.

Dependendo do ambiente de desenvolvimento integrado ou editor que você prefere usar, é possível instalar um plug-in ou aplicar o suporte integrado para usar o esquema de Workflows. O esquema pode ser armazenado localmente na raiz do projeto ou especificado pelo URL do recurso em SchemaStore.org.

Formato de nome de arquivo para arquivos de definição de fluxo de trabalho

Independentemente do ambiente de desenvolvimento integrado ou editor que você usa, se estiver usando um plug-in ou uma extensão para aplicar automaticamente o esquema Workflows do SchemaStore.org, o formato de nome do arquivo de definição do fluxo de trabalho precisa ser o seguinte:

  • workflows.json
  • workflows.yaml
  • workflows.yml
  • *.workflows.json
  • *.workflows.yaml
  • *.workflows.yml

Se você estiver usando o VS Code ou o suporte integrado para aplicar o esquema de Workflows, poderá substituir os formatos de nome de arquivo.

Limitações

O suporte à sintaxe pelo esquema JSON dos fluxos de trabalho se concentra na autopreenchimento de palavras-chave que definem um fluxo de trabalho. O esquema oferece suporte à autopreenchimento para algumas funções de biblioteca padrão, mas há suporte limitado para nomes de variáveis dinâmicas, expressões e outros ajudantes de expressão. O esquema também pressupõe que um fluxo de trabalho está completo e não considera nenhum pós-processamento, como a combinação de subfluxos de trabalho.

Para evitar conflitos de esquema JSON, recomendamos que você não use mais de uma extensão ou plug-in para suporte à sintaxe de Workflows.

Associar o esquema JSON dos fluxos de trabalho no VS Code

O VS Code é um editor de código-fonte executado no computador e está disponível para Windows, macOS e Linux. Ele tem suporte integrado para várias linguagens e oferece suporte a extensões para outras linguagens e ambientes de execução. Para instalar e configurar o VS Code na sua máquina, consulte Visual Studio Code.

Confira a seguir várias maneiras de associar o esquema JSON Workflows no VS Code.

Usar o Cloud Code para criar fluxos de trabalho em YAML

O Cloud Code é um conjunto de plug-ins de ambiente de desenvolvimento integrado que facilita a criação, a implantação e a integração de aplicativos com o Google Cloud.

Se você estiver usando o VS Code como seu ambiente de desenvolvimento integrado, use o Cloud Code ao criar seus fluxos de trabalho YAML, e ele vai extrair automaticamente o esquema JSON dos fluxos de trabalho do SchemaStore.org. Para confirmar que o esquema está sendo aplicado conforme esperado, crie um fluxo de trabalho YAML em um espaço de trabalho ou pasta do VS Code e confirme se a conclusão automática está ocorrendo para as palavras-chave do Workflows.

O Cloud Code também oferece suporte a esquemas do Google Cloud off-line e pode ser usado por pessoas que têm restrições de rede ou IDE. Para mais informações, consulte:

Usar o YAML do RedHat para criar fluxos de trabalho em YAML

Como alternativa à extensão do Cloud Code para VS Code, você pode usar a extensão YAML do RedHat. Essa extensão oferece suporte à linguagem YAML e inclui suporte à sintaxe integrada do Kubernetes. Ele extrai automaticamente o esquema JSON dos fluxos de trabalho do SchemaStore.org.

Depois de instalar a extensão, crie um fluxo de trabalho YAML. Na parte de cima do arquivo, há um link para o arquivo de configuração do Google Cloud Workflows (workflows.json). Se você clicar no link, o esquema JSON do Workflows será aberto no editor do VS Code.

Substituir os formatos de nome de arquivo

Ao usar o Cloud Code ou o YAML do RedHat para criar fluxos de trabalho em YAML, é possível substituir os formatos de nome de arquivo padrão em que o esquema de Workflows é aplicado. É necessário especificar um mapeamento no arquivo settings.json. As configurações são gravadas como JSON, e você pode analisar e editar esse arquivo diretamente abrindo-o no editor do VS Code.

Por exemplo, se você estiver usando a extensão do Cloud Code para VS Code, é possível mapear um formato de nome de arquivo na propriedade cloudcode.yaml.schemas:

{
    "cloudcode.yaml.schemas": {
        "https://json.schemastore.org/workflows.json": [
            "GLOB_PATTERN.yaml",
            "my-special-workflow.yaml"
        ]
    }
}

Ou, se você estiver usando a extensão YAML do RedHat, mapeie o formato do nome do arquivo na propriedade yaml.schemas:

{
    "yaml.schemas": {
        "https://json.schemastore.org/workflows.json": [
            "GLOB_PATTERN.yaml",
            "my-special-workflow.yaml"
        ]
    }
}

Os esquemas à esquerda são aplicados aos padrões de glob à direita. Cada esquema é associado a vários globs usando uma matriz JSON. O esquema precisa ser um caminho relativo, não absoluto. O esquema pode ser local ou on-line.

Usar o suporte integrado para criar fluxos de trabalho em JSON

É possível usar o suporte integrado no VS Code para associar o esquema JSON Workflows especificando o mapeamento no arquivo settings.json, na propriedade json.schemas. Você pode analisar e editar esse arquivo diretamente abrindo-o no editor do VS Code.

Por exemplo, para extrair o esquema JSON de fluxos de trabalho da SchemaStore.org:

{
    "json.schemas": [
        {
            "description": "SchemaStore.org",
            "fileMatch": [
                "workflows.json",
                "*.workflows.json"
            ],
            "url": "https://json.schemastore.org/workflows.json"
         }
    ]
}

Os esquemas à esquerda são aplicados aos padrões de glob à direita. Um esquema é associado a vários globs usando uma matriz JSON. O esquema precisa ser um caminho relativo, não absoluto. O esquema pode ser local ou on-line.

É possível substituir o formato do nome do arquivo. Exemplo:

{
    "json.schemas": [
        {
            "description": "Workflows schema",
            "fileMatch": [
                "GLOB_PATTERN.json",
                "FILE_NAME.json"
            ],
            "url": "https://json.schemastore.org/workflows.json"
        }
    ]
}

Para mais informações, consulte Como editar JSON com o Visual Studio Code.

Associar o esquema JSON dos fluxos de trabalho no IntelliJ IDEA

O IntelliJ IDEA é um ambiente de desenvolvimento integrado multiplataforma para linguagens de máquina virtual Java. Outras línguas têm suporte por meio de plug-ins. Para instalar e configurar o IntelliJ IDEA na sua máquina, consulte Instalar o IntelliJ IDEA.

Confira a seguir várias maneiras de associar o esquema JSON de Workflows no IntelliJ IDEA.

Usar o Cloud Code para criar fluxos de trabalho em YAML ou JSON

O Cloud Code é um conjunto de plug-ins de ambiente de desenvolvimento integrado que facilita a criação, a implantação e a integração de aplicativos com o Google Cloud.

Se você estiver usando o IntelliJ como ambiente de desenvolvimento integrado, poderá usar o Cloud Code ao criar seus fluxos de trabalho em YAML ou JSON, e ele extrairá automaticamente o esquema JSON dos fluxos de trabalho do SchemaStore.org. O Cloud Code também oferece suporte a esquemas do Google Cloud off-line e pode ser usado por pessoas que têm restrições de rede ou IDE. Para mais informações, consulte as seguintes seções:

Usar o suporte integrado para criar fluxos de trabalho em YAML ou JSON

O IntelliJ IDEA pode fazer o download e usar esquemas do SchemaStore.org automaticamente. É possível fazer o download do esquema JSON do Workflows e armazená-lo na raiz do projeto ou especificar o URL do recurso para que o IntelliJ IDEA possa fazer o download do esquema automaticamente. Para mapear o esquema, siga as instruções para configurar um esquema JSON personalizado.

Por padrão, os downloads automáticos de esquemas do SchemaStore.org são ativados, e os padrões de nome de arquivo padrão são validados pelo esquema.

Para substituir os padrões de arquivo padrão, depois de navegar até as Mapeamentos de esquema JSON na caixa de diálogo Configurações, faça o seguinte:

  1. No campo Nome, digite Esquema de fluxos de trabalho.
  2. No campo Arquivo ou URL do esquema, digite https://json.schemastore.org/workflows.json.
  3. Na lista Versão do esquema, selecione Versão 7 do esquema JSON.
  4. Adicione um Padrão de caminho de arquivo de sua escolha.

Mapear o esquema pelo jsonSchema.xml

O código-fonte do IntelliJ IDEA Edição da Comunidade está disponível em https://github.com/JetBrains/intellij-community.

É possível mapear o esquema JSON de fluxos de trabalho para o editor IntelliJ IDEA adicionando uma entrada a jsonSchemas.xml.

Adicionar a validação de sintaxe do Workflows aos seus processos de CI/CD

Adicionar a validação de sintaxe aos processos de integração, entrega e implantação contínua (CI/CD, na sigla em inglês) ajuda a reduzir erros durante a integração, o teste, a entrega e a implantação.

Por exemplo, é possível validar dados com base no esquema JSON dos fluxos de trabalho usando a ferramenta ajv-cli. Ao instalar a ferramenta, também instale o ajv-formats. Exemplo:

npm install -g ajv-cli ajv-formats

Outras ferramentas que podem ser úteis:

  • MegaLinter v8r: o MegaLinter é uma ferramenta de código aberto para fluxos de trabalho de CI/CD. O v8r verifica a validade de arquivos JSON/YAML se eles têm um esquema correspondente definido no SchemaStore.org.
  • Validadores JSON: ferramentas de validação JSON categorizadas por linguagem de programação ou plataforma de desenvolvimento.

A seguir