# Network List API

A Network List API do Azion Runtime verifica se um endereço IP está em uma das [network lists](/pt-br/documentacao/plataforma/firewall/network-shield/network-lists/) da sua conta. Functions executadas em uma Application ou em um Firewall podem chamá-la. Passe a ela o endereço do cliente da requisição para permitir, negar ou rotear essa requisição de acordo com a origem dela.

> **nota**
>
> Com `azion dev`, toda chamada a `Azion.networkList.contains()` lança `TypeError: Cannot read properties of undefined (reading 'find')`. Teste as verificações de network list em uma function com deploy feito.

---

## Acesso

A API é a função `Azion.networkList.contains()`, disponível em toda function sem import. O endereço do cliente de uma requisição é o valor `remote_addr` dos metadados da requisição. Com o handler `export default { fetch }`, leia-o em `request.metadata`:

```javascript
const ip = request.metadata["remote_addr"];
```

Com `addEventListener("fetch", ...)`, leia-o em `event.request.metadata`:

```javascript
let ip = event.request.metadata["remote_addr"];
```

Para conhecer todos os valores de metadados que uma function pode ler, consulte [API de metadados](/pt-br/documentacao/devtools/runtime/api-reference/metadata/).

---

## Sintaxe

`Azion.networkList.contains()` recebe o ID da network list e o endereço a verificar:

```javascript
Azion.networkList.contains(networkListId, ipAddress)
```

---

## Parâmetros

Os dois parâmetros são strings.

| Parâmetro       | Tipo   | Descrição                                                                                                                                                                       |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `networkListId` | string | ID da network list, como uma string de dígitos. Um número não é aceito: converta-o com `String()` antes.                                                                        |
| `ipAddress`     | string | Endereço IP a verificar. Ele corresponde a um item de endereço da lista ou a qualquer endereço dentro de um item CIDR, por exemplo `198.51.100.42` dentro de `198.51.100.0/24`. |

---

## Valor de retorno

`Azion.networkList.contains()` retorna um booleano: `true` quando o endereço está na network list e `false` quando não está. Quando a chamada não consegue executar a verificação, ela lança um `NetworkListError`, listado em Erros.

---

## Exemplo

Esta function verifica o endereço do cliente de cada requisição em uma network list e retorna o resultado como JSON. Substitua `<network-list-id>` pelo ID de uma das suas network lists:

```javascript
const NETWORK_LIST_ID = "<network-list-id>";

export default {
  async fetch(request, env, ctx) {
    const ip = request.metadata["remote_addr"];
    const ipFound = Azion.networkList.contains(NETWORK_LIST_ID, ip);
    return new Response(JSON.stringify({ ipFound }, null, 1), {
      headers: { "content-type": "application/json" },
    });
  },
};
```

Uma requisição de um endereço que está na lista retorna:

```json
{
 "ipFound": true
}
```

---

## Erros

Todo erro que `Azion.networkList.contains()` lança tem o nome `NetworkListError`. Capture-o com `try...catch` e compare `err.name` para decidir o que a function faz quando a verificação não pode ser executada.

| Mensagem de erro                                              | Causa                                                                                      | Correção                                                                     |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `Network List Not Found`                                      | O ID não corresponde a nenhuma network list da conta, ou o ID foi passado como número.     | Passe o ID de uma network list existente como uma string de dígitos.         |
| `Invalid Network List Id: Only numeric values are acceptable` | A string do ID contém caracteres que não são dígitos.                                      | Passe o ID numérico da network list como string.                             |
| `Invalid value: not-an-ip`                                    | O endereço não é um endereço IP. A mensagem termina com o valor passado, aqui `not-an-ip`. | Passe um endereço IP, como o valor de metadados `remote_addr` da requisição. |

---

## Recursos relacionados

- [Network Lists](/pt-br/documentacao/plataforma/firewall/network-shield/network-lists.md): Os tipos de lista, o formato dos itens e as interfaces que criam e editam uma lista.
- [API de metadados](/pt-br/documentacao/devtools/runtime/api-reference/metadata.md): Leia o `remote_addr` de uma requisição e os outros valores que o runtime fornece a uma function.
- [Functions no Firewall](/pt-br/documentacao/plataforma/firewall/functions.md): Termine uma function de firewall com `event.continue()`, `event.deny()` ou `event.drop()` após uma verificação.
- [Handlers](/pt-br/documentacao/devtools/runtime/api-reference/handlers.md): As formas de handler `export default { fetch }` e `addEventListener` e a requisição que cada uma recebe.