# API de metadados

A API de metadados do Azion Runtime fornece a uma function um conjunto de valores sobre cada requisição: a localização GeoIP do cliente, o endereço e a porta dele, o protocolo, a sessão TLS, fingerprints e identificadores. Functions executadas em uma Application ou em um Firewall podem lê-la. Use-a para filtrar e gerenciar o acesso à sua aplicação ou para aplicar uma lógica diferente para cada cenário.

> **nota**
>
> Com `azion dev`, o objeto de metadados é `undefined`. Teste a leitura dos metadados em uma function com deploy feito.

---

## Acesso

Os metadados são um objeto na requisição. Com o handler `export default { fetch }`, leia-os em `request.metadata`:

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

Com `addEventListener("fetch", ...)` ou `export default main`, leia-os em `event.request.metadata`:

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

Todo valor é uma string ou `null`.

---

## GeoIP

As chaves GeoIP localizam o cliente a partir do endereço IP dele.

| Chave                       | Descrição                               |
| --------------------------- | --------------------------------------- |
| `geoip_asn`                 | Número do sistema autônomo.             |
| `geoip_city`                | Código da cidade.                       |
| `geoip_city_continent_code` | Código do continente da cidade.         |
| `geoip_city_country_code`   | Código do país da cidade.               |
| `geoip_city_country_name`   | Nome do país da cidade.                 |
| `geoip_continent_code`      | Código do continente, por exemplo `SA`. |
| `geoip_country_code`        | Código do país, por exemplo `BR`.       |
| `geoip_country_name`        | Nome do país, por exemplo `Brazil`.     |
| `geoip_region`              | Código da região.                       |
| `geoip_region_name`         | Nome da região.                         |

---

## Remote

As chaves remote descrevem a conexão do cliente.

| Chave         | Descrição                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| `remote_addr` | Endereço IP do cliente.                                                                                           |
| `remote_port` | Porta TCP do cliente.                                                                                             |
| `remote_user` | Usuário informado na URL, por exemplo `user` em `https://user@example.com/`. `null` quando a URL não tem usuário. |

---

## Server

A chave server informa o protocolo da requisição.

| Chave             | Descrição                                        |
| ----------------- | ------------------------------------------------ |
| `server_protocol` | Protocolo da requisição, por exemplo `HTTP/2.0`. |

---

## TLS

As chaves TLS descrevem a sessão TLS da requisição.

| Chave          | Descrição                                                  |
| -------------- | ---------------------------------------------------------- |
| `ssl_cipher`   | Cifra TLS da sessão, por exemplo `TLS_AES_256_GCM_SHA384`. |
| `ssl_protocol` | Protocolo TLS da sessão, por exemplo `TLSv1.3`.            |

---

## Fingerprints

As chaves de fingerprint carregam fingerprints TLS e HTTP para análise de segurança.

| Chave                     | Descrição                          |
| ------------------------- | ---------------------------------- |
| `server_fingerprint`      | Fingerprint TLS do servidor.       |
| `server_fingerprint_ja4h` | Fingerprint JA4H do servidor.      |
| `http_ssl_ja4`            | Fingerprint TLS JA4 da requisição. |
| `client_fingerprint`      | Fingerprint do cliente, ou `null`. |

---

## Identificadores

As chaves de identificador indicam a conta e os recursos que processam a requisição.

| Chave              | Descrição                                                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `solution_id`      | Identificador interno da solução (conjunto de produtos) que processa a requisição.                                                     |
| `client_id`        | Identificador da conta Azion proprietária do workload.                                                                                 |
| `function_id`      | Identificador da function executada para a requisição.                                                                                 |
| `configuration_id` | Identificador do workload que recebeu a requisição.                                                                                    |
| `virtualhost_id`   | O identificador do workload seguido do `client_id`.                                                                                    |
| `connector_id`     | Identificador do connector, quando a requisição passa por um. Um traço (`-`) quando nenhum connector participa.                        |
| `request_id`       | ID único da requisição, o mesmo valor do header de resposta `x-azion-request-id`. Use-o para rastrear uma requisição de ponta a ponta. |

---

## Exemplo

Esta function retorna o objeto de metadados completo da requisição em JSON:

```javascript
addEventListener("fetch", (event) => {
  const metadata = event.request.metadata;
  event.respondWith(new Response(JSON.stringify(metadata, null, 1), {
    headers: { "content-type": "application/json" },
  }));
});
```

Uma requisição à function com deploy feito retorna o objeto abaixo. O endereço do cliente é um endereço de documentação e a cidade é um placeholder:

```json
{
 "server_fingerprint": "t13d4007h2_731077d8320c_7395dae3b2f3",
 "server_fingerprint_ja4h": "ge20nn030000_b5531655046c_e3b0c44298fc_e3b0c44298fc",
 "client_fingerprint": null,
 "http_ssl_ja4": "t13d4007h2_731077d8320c_7395dae3b2f3",
 "geoip_asn": "64496",
 "geoip_city": "<city>",
 "geoip_city_continent_code": "SA",
 "geoip_city_country_code": "BR",
 "geoip_city_country_name": "Brazil",
 "geoip_continent_code": "SA",
 "geoip_country_code": "BR",
 "geoip_country_name": "Brazil",
 "geoip_region": "<region>",
 "geoip_region_name": "<region-name>",
 "remote_addr": "192.0.2.10",
 "remote_port": "5710",
 "remote_user": null,
 "server_protocol": "HTTP/2.0",
 "ssl_cipher": "TLS_AES_256_GCM_SHA384",
 "ssl_protocol": "TLSv1.3",
 "solution_id": "1531930033",
 "client_id": "1234u",
 "function_id": "12345",
 "configuration_id": "1234567890",
 "virtualhost_id": "12345678901234u",
 "connector_id": "-",
 "request_id": "0123456789abcdef0123456789abcdef"
}
```

---

## Recursos relacionados

- [Network List API](/pt-br/documentacao/devtools/runtime/api-reference/network-list.md): Verifique se o `remote_addr` de uma requisição está em uma das suas network lists.
- [Handlers](/pt-br/documentacao/devtools/runtime/api-reference/handlers.md): Os formatos de handler que uma function exporta e a requisição que cada um recebe.
- [Functions](/pt-br/documentacao/plataforma/functions.md): Como uma function é criada, instanciada em uma application ou em um firewall e invocada por uma regra.
- [Functions no Firewall](/pt-br/documentacao/plataforma/firewall/functions.md): O evento e os métodos que uma function em um Firewall usa para permitir, negar, descartar ou responder a uma requisição.