# Primeiros passos com a Azion API Este guia orienta você nas suas primeiras requisições à Azion API. - Obtenha um personal token para autenticar as suas requisições. - Liste os workloads da sua conta. - Crie uma network list. - Leia a network list e renomeie-a. - Exclua a network list e confirme que ela não existe mais. Toda requisição vai para a URL base `https://api.azion.com/v4` e leva o seu personal token no header `Authorization`. O guia cria um único objeto, uma [network list](/pt-br/documentacao/plataforma/firewall/network-shield/network-lists/) com um endereço IP, e não o vincula a mais nada. Você o exclui na última etapa, e a conta termina como começou. A Azion CLI chega aos mesmos resultados pelo terminal. Cada etapa mostra a requisição à API e o comando da CLI que corresponde a ela. Para todos os endpoints, com exemplos de requisição em `curl` e em outras linguagens, consulte a [referência da Azion API](https://api.azion.com/). --- Escolha API ou CLI uma vez. Os pré-requisitos e as cinco etapas mudam para essa interface. ## Pré-requisitos - Uma conta Azion. Para criar uma, consulte [Criar uma conta](/pt-br/documentacao/fundamentos/criar-uma-conta/). **API** - `curl` ou outro cliente HTTP. **CLI** - A [Azion CLI](/pt-br/documentacao/devtools/cli/) instalada. Para instalá-la, consulte [Primeiros passos com a Azion CLI](/pt-br/documentacao/devtools/cli/primeiros-passos/). --- ## Obtenha um personal token Um [personal token](/pt-br/documentacao/fundamentos/personal-tokens/) autentica as suas requisições à Azion API e à Azion CLI. Para criar um no Azion Console, consulte [Gerencie personal tokens](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). Copie o token quando o Azion Console o exibir, porque você só consegue vê-lo no momento em que o cria. **API** A Azion API lê o token do header `Authorization`. Toda requisição deste guia o envia nesta forma: ```text Authorization: Token [TOKEN VALUE] ``` A API também aceita um personal token com o esquema `Bearer`: `Authorization: Bearer [TOKEN VALUE]`. Você tem o header que autentica todas as requisições das próximas etapas. **CLI** Salve o token na Azion CLI. Substitua `[TOKEN VALUE]` pelo seu token: ```bash azion -t [TOKEN VALUE] ``` A CLI guarda o token na pasta de configuração dela, e os comandos seguintes o usam sem a flag. Para mais informações sobre a configuração da CLI, consulte [Primeiros passos com a Azion CLI](/pt-br/documentacao/devtools/cli/primeiros-passos/). --- ## Liste os seus workloads Uma requisição de listagem retorna os workloads da sua conta e confirma que o token funciona. A resposta é uma página de resultados. **API** Envie uma requisição `GET` ao endpoint de workloads. O parâmetro `page_size=100` pede até 100 workloads em uma página, e `fields=id` retorna apenas o ID de cada workload: ```bash curl --request GET \ --url 'https://api.azion.com/v4/workspace/workloads?page_size=100&fields=id' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` Um `200` retorna a página de workloads: ```json { "count": 17, "total_pages": 1, "page": 1, "page_size": 100, "next": null, "previous": null, "results": [ {"id": 1234567890}, {"id": 1234567891}, {"id": 1234567892}, {"id": 1234567893}, {"id": 1234567894}, {"id": 1234567895}, {"id": 1234567896}, {"id": 1234567897}, {"id": 1234567898}, {"id": 1234567899}, {"id": 1234567900}, {"id": 1234567901}, {"id": 1234567902}, {"id": 1234567903}, {"id": 1234567904}, {"id": 1234567905}, {"id": 1234567906} ] } ``` O campo `count` contém o número de workloads da conta, e `results` contém os workloads da página. Uma resposta de listagem traz `count`, `total_pages`, `page`, `page_size`, `next`, `previous` e `results`. Para paginação, `fields`, `ordering` e `search`, consulte [Azion API](/pt-br/documentacao/devtools/api/). **CLI** Liste os workloads com a Azion CLI. A flag `--page-size 1` retorna um workload, e `--details` adiciona colunas: ```bash azion list workload --page-size 1 --details ``` O comando imprime uma linha para o workload: ```text ID NAME ACTIVE LAST EDITOR LAST MODIFIED 1234567890 my-blog true you@example.com 2026-01-01 12:00:00.000000 +0000 UTC ``` Sem `--page-size`, `azion list workload` imprime o ID e o nome de todos os workloads da conta. --- ## Crie uma network list Uma network list contém um conjunto de valores de um único tipo. A requisição precisa de um `name`, de um `type` e dos `items` da lista. O `type` aceita `ip_cidr`, `asn` ou `countries`, e `items` aceita de 1 a 20.000 entradas. Este guia cria uma lista `ip_cidr` com um endereço do intervalo de documentação `192.0.2.0/24`. **API** Envie uma requisição `POST` ao endpoint de network lists: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/network_lists \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{"name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"]}' ``` Um `201` retorna a network list dentro de `data`, com `"state": "executed"`: ```json { "state": "executed", "data": { "id": 1234567890, "name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` O campo `active` assume `true` como padrão quando a requisição o omite. Anote o `id`. As próximas etapas o enviam na URL. **CLI** Crie a network list com a Azion CLI: ```bash azion create network-list --name my-ip-list --type ip_cidr --items 192.0.2.10 ``` O comando imprime o ID da network list: ```text Created Network List with ID 12345 ``` Anote o ID. As próximas etapas o passam para `--network-list-id`. --- ## Leia e renomeie a network list A leitura da network list retorna os valores atuais dela. Uma renomeação altera um campo e mantém os outros como estão. **API** Envie uma requisição `GET` à network list. Substitua `` pelo `id` que a requisição de criação retornou: ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` Um `200` retorna a network list dentro de `data`: ```json { "data": { "id": 1234567890, "name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` Para renomear a network list, envie uma requisição `PATCH` apenas com o novo `name`: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{"name": "my-ip-list-renamed"}' ``` Um `200` retorna a network list com o novo nome e um novo `last_modified`: ```json { "state": "executed", "data": { "id": 1234567890, "name": "my-ip-list-renamed", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:01:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` Os campos `type` e `items` mantêm os valores da requisição de criação. **CLI** Descreva a network list. Substitua `` pelo ID que o comando de criação imprimiu: ```bash azion describe network-list --network-list-id ``` O comando imprime o nome, o tipo, os itens e o estado da network list: ```text ID: 12345 Name: my-ip-list Type: ip_cidr Items: ["192.0.2.10"] Last Editor: you@example.com Last Modified: "2026-01-01T12:00:00.000000Z" Active: true ``` Renomeie a network list: ```bash azion update network-list --network-list-id --name my-ip-list-renamed ``` O comando confirma a atualização: ```text Updated Network List with ID 12345 ``` Descreva a network list novamente: ```bash azion describe network-list --network-list-id ``` A saída mostra o novo nome e um novo valor em **Last Modified**, e o tipo e os itens não mudam: ```text ID: 12345 Name: my-ip-list-renamed Type: ip_cidr Items: ["192.0.2.10"] Last Editor: you@example.com Last Modified: "2026-01-01T12:01:00.000000Z" Active: true ``` --- ## Exclua a network list A exclusão da network list devolve a conta ao estado que ela tinha antes de você criar a lista. **API** Envie uma requisição `DELETE` à network list: ```bash curl --request DELETE \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` Um `200` retorna apenas o estado da operação: ```json {"state": "executed"} ``` Para confirmar a exclusão, envie novamente a requisição `GET` que leu a lista. Um `404` retorna o envelope de erro: ```json {"errors": [{"code": "10004", "title": "Not Found", "detail": "Not found.", "status": "404"}]} ``` A network list não existe mais. **CLI** Exclua a network list com a Azion CLI: ```bash azion delete network-list --network-list-id ``` O comando confirma a exclusão: ```text Network List 12345 was successfully deleted ``` Para confirmar a exclusão, descreva a network list novamente: ```bash azion describe network-list --network-list-id ``` O comando sai com o status `1` e imprime o erro: ```text Error: Failed to describe Network List: The given ID or API's endpoint doesn't exist or isn't available. Check that the identifying information is correct ``` A network list não existe mais. --- ## Próximos passos - [Azion API](/pt-br/documentacao/devtools/api.md): A URL base, a autenticação, a paginação, os parâmetros de query e os limites de requisição da API. - [Solucionar problemas da Azion API](/pt-br/documentacao/devtools/api/solucao-de-problemas.md): Causas e correções dos erros que a API retorna, por código de status. - [Network lists](/pt-br/documentacao/plataforma/firewall/network-shield/network-lists.md): Os campos, os tipos de lista e os erros de uma network list, e como uma regra de firewall a compara. - [Azion CLI network-list](/pt-br/documentacao/devtools/cli/recursos/network-list.md): Todas as flags dos comandos que criam, listam, descrevem, atualizam e excluem network lists.