Criar Plugin de Aplicação com o STK CLI

Neste guia, você vai aprender a criar dois Plugins de Aplicação na StackSpot EDP utilizando o STK CLI. O exemplo prático envolve uma API em Python desenvolvida com o microframework Flask.

Visão Geral do Plugin de Aplicação

Criar um Plugin de Aplicação na StackSpot EDP significa desenvolver o código de uma Aplicação, ou parte dele, dentro da estrutura de Plugins de Aplicação da StackSpot. O Plugin pode representar tanto uma aplicação base minimamente funcional quanto um trecho de código que adiciona novas funcionalidades a uma Aplicação existente.

Ao estruturar seu código como Plugin, você facilita o reuso e o compartilhamento de soluções de forma padronizada e controlada em equipes ou organizações.

Na estrutura do Plugin de Aplicação, utilize os seguintes componentes:

Documentação do Plugin: utilize a pasta docs para fornecer informações sobre o uso do Plugin. A documentação pode ser escrita em português (pt-br) e inglês (en-us).
Código da Aplicação: insira todos os arquivos e códigos-fonte que compõem a Aplicação ou parte dela na pasta templates. Esse conteúdo será gerado quando o Plugin for executado.
Casos de Teste: armazene cenários de teste do Plugin na pasta tests. Isso é especialmente útil para Plugins com muitos inputs ou que geram múltiplos arquivos.
Configuração do Plugin: o arquivo plugin.yaml centraliza as configurações do Plugin, incluindo tipos de inputs, Hooks Declarativos e Connection Interfaces, tornando o Plugin mais dinâmico e inteligente.

Pré-requisitos e Permissões

Antes de começar, verifique se você possui acesso e permissão para criar ou utilizar um Studio na StackSpot EDP. Consulte os recursos a seguir para mais informações:

Etapa 1. Criar a Estrutura dos Plugins

Crie uma pasta para os Plugins e acesse-a pelo terminal:
```
mkdir Flask-API
cd Flask-API
```
Execute o comando a seguir para iniciar a criação do Plugin flask-api-plugin e responda às perguntas sobre nome, tipo e outras configurações:
```
stk create plugin
```
nota
As perguntas envolvem o preenchimento de metadados obrigatórios do Plugin, como nome, tipo, descrição e versão. Algumas perguntas permitem pré-configurar recursos, por exemplo, Connection Interfaces ou inicialização de repositório Git.
Execute novamente o comando para criar o Plugin add-endpoint-to-flask-application:
```
stk create plugin
```
Responda aos prompts com as informações necessárias para o novo Plugin.

Etapa 2. Implementar o Código do Plugin `flask-api-plugin`

No diretório do Plugin flask-api-plugin, acesse a pasta templates.

Crie o arquivo main.py e insira o código de exemplo:

main.py
from flask import Flask, jsonify, request

app = Flask(__name__)

# Sample data
users = [
    {"id": 1, "name": "John Doe"},
    {"id": 2, "name": "Jane Doe"}
]

@app.route('/')
def home():
    return "Welcome to the Flask API!"

@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify(users)

if __name__ == '__main__':
    app.run(debug=True)

Etapa 3. Adaptar o Código para Inputs Dinâmicos com Jinja

Agora, utilize expressões Jinja para tornar o código dinâmico, permitindo personalização via inputs do Plugin.

No arquivo main.py, faça as seguintes substituições:
- Substitua a lista users por {{ sample_data }}
- Substitua a rota '/api/users' por '/{{ subdirectory }}/{{ path }}'
- Substitua o método 'GET' em methods=[ ] por {{ method }}
- Renomeie a função def get_users() para def {{ method | lower }}_{{ subdirectory }}():

O código atualizado ficará assim:

main.py
from flask import Flask, jsonify, request

app = Flask(__name__)

# Sample data
users = {{ sample_data }}

@app.route('/')
def home():
    return "Welcome to the Flask API!"

@app.route('/{{ subdirectory }}/{{ path }}', methods=['{{method}}'])
def {{ method | lower }}_{{ subdirectory }}():
    return jsonify(users)

if __name__ == '__main__':
    app.run(debug=True)

Etapa 4. Configurar o Arquivo `plugin.yaml` do Plugin `flask-api-plugin`

No arquivo plugin.yaml, remova o bloco de inputs padrão.

Insira o seguinte bloco de inputs, alinhando as variáveis com as expressões Jinja do passo anterior:

dica

Os nomes dos inputs são as variáveis utilizadas no código do Plugin com Jinja.

Inputs do plugin.yaml
inputs:
  - label: Type the subdirectory of your URL
    name: subdirectory
    type: text
    required: true
    default: users
    pattern: '([a-z]+)+'
  - label: Type the path of your URL
    name: path
    type: text
    required: true
    default: id
    pattern: '([a-z]+)+'
  - label: Sample Data
    name: sample_data
    type: list
    add-question: Add one more user?
    input:
      label: User Sample data
      type: object
      inputs:
        - name: id
          type: int
          label: User ID
        - name: user_name
          type: text
          label: User Name
  - label: Choose the http method of the new endpoint
    name: method
    type: select
    items:
      - GET
      - POST
      - PUT
      - DELETE
      - PATCH
    default: GET
    required: true

Etapa 5. Criar a Documentação do Plugin

Uma documentação clara e completa melhora a experiência de quem utiliza o Plugin. Siga o exemplo para iniciar a documentação do seu Plugin:

Na pasta docs, selecione o idioma desejado e edite o arquivo docs.md. Inclua os requisitos do Plugin:

docs.md
## Nome do Plugin

Descreva de forma concisa o objetivo do seu Plugin.

## Requisitos

- Flask==3.0.3
- jsonify==0.5
- requests==2.32.3

## Uso

Forneça instruções sobre como utilizar o Plugin, incluindo:
- Parâmetros de entrada (inputs)
- Métodos suportados
- Recursos criados
- Estrutura de arquivos do diretório do Plugin
- Quaisquer dependências adicionais

## Notas de Lançamento

Esta seção é opcional e deve ser usada para registrar alterações ou melhorias em novas versões do Plugin.

Testar o Plugin (Recomendado)

Teste o comportamento do seu Plugin utilizando casos de teste. Para saber mais, consulte o Guia de Testes de Plugins.

Etapa 6. Implementar o Plugin `add-endpoint-to-flask-application`

Esse Plugin complementa o anterior, permitindo adicionar endpoints a Aplicações criadas com o flask-api-plugin, usando um Hook Declarativo.

No diretório do Plugin add-endpoint-to-flask-application, crie a pasta snippets.

Dentro de snippets, crie o arquivo flask-endpoint.txt com o seguinte conteúdo:

flask-endpoint.txt
@app.route('/{{ subdirectory }}/{{ path }}', methods=['{{method}}'])
def {{ method | lower }}_{{ subdirectory }}():
    return jsonify(users)

Etapa 7. Configurar o Arquivo `plugin.yaml` do Plugin `add-endpoint-to-flask-application`

No arquivo plugin.yaml, remova o bloco inicial de inputs.

Insira o seguinte bloco, incluindo o Hook Declarativo para editar o arquivo main.py:

inputs:
  - label: Type the subdirectory of your URL
    name: subdirectory
    type: text
    required: true
    default: users
    pattern: '([a-z]+)+'
  - label: Type the path of your URL
    name: path
    type: text
    required: true
    default: id
    pattern: '([a-z]+)+'
  - label: Choose the http method of the new endpoint
    name: method
    type: select
    items:
      - GET
      - POST
      - PUT
      - DELETE
      - PATCH
    default: GET
    required: true
hooks:
  - type: edit
    trigger: after-render
    path: main.py
    changes:
      - search:
          string: "if __name__ == '__main__':"
          insert-before:
            snippet: snippets/flask-endpoint.txt

Etapa 8. Publicar os Plugins

Publicar um Plugin na StackSpot significa armazená-lo e disponibilizá-lo na plataforma. Para cada Plugin:

Certifique-se de estar autenticado na StackSpot. Execute:
```
stk login seu-email@stackspot.com
```
No diretório do Plugin, execute:
```
stk publish plugin
```
Selecione um Studio da sua conta e aguarde a conclusão da publicação.

Próximos Passos e Recursos Relacionados

Ao finalizar este guia, você terá criado um Plugin que gera uma API simples em Python usando Flask e outro Plugin que adiciona endpoints a Aplicações criadas com o primeiro Plugin.

Para aprofundar nos conceitos apresentados, consulte: