# Biblioteca `Domains` da Azion

import DocButton from '~/components/webkit/DocButton.vue';

A biblioteca **Domains** da Azion fornece uma interface simples para interagir com a API de **Domains**, permitindo que você crie, liste, obtenha, atualize e exclua domínios.

<DocButton href="/pt-br/documentacao/produtos/azion-lib/visao-geral/" label="Saiba mais sobre as Azion Libraries" kind="secondary" size="medium" />

Você pode interagir com a API usando um `client` ou chamando os métodos diretamente da biblioteca. Quando faz chamadas diretas, você pode usar as variáveis de ambiente para configurar o `client` sem passar os parâmetros de token e debug diretamente.

Exemplo de um arquivo `.env` com suas variáveis de ambiente:

```sh
AZION_TOKEN=<your-api-token>
AZION_DEBUG=true
```

| Variável | Descrição |
|----------|-------------|
| `AZION_TOKEN` | Seu token de API da Azion. |
| `AZION_DEBUG` | Ativar o modo de debug (true/false). |

:::tip
Configurar `AZION_DEBUG` para `true` ativa o **modo de debug**. Este modo fornece logs detalhados das requisições e respostas da API.
:::

Se você deseja criar um `client` específico para interagir com **Domains**, crie um chamando o método `createClient` da biblioteca:

```typescript
import { createClient } from 'azion/domains';
import type { AzionDomain, AzionDomainsClient } from 'azion/domains';

const client: AzionDomainsClient = createClient({ token: 'your-api-token', { debug: true } });

const { data: newDomain, error }: AzionDomainsResponse<AzionDomain> = await client.createDomain({ name: 'example domain', edgeApplicationId: 123 });
if (newDomain) {
  console.log(`Domain created with ID: ${newDomain.id}`);
}
```

O método `createClient` tem os seguintes **parâmetros** e **retorno**:

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `config` | `Partial<{ token: string; options?: OptionsParams }>` | Opções de configuração para o cliente de Domains. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `AzionDomainsClient` | Um objeto com métodos para interagir com Domains. |

:::note
Nos exemplos a seguir, os métodos são chamados diretamente sem a criação de um `client`. Para obter mais informações sobre como interagir com serviços e produtos usando um `client`, consulte a documentação do [Azion Lib Client](/pt-br/documentacao/produtos/azion-lib/client/).
:::

---

## Uso

### `createDomain`

Este método cria um novo domínio. Por exemplo:

```typescript
import { createDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await createDomain({
  name: 'example domain',
  edgeApplicationId: 123,
});
if (domain) {
  console.log(`Domain created with ID: ${domain.id}`);
} else {
  console.error('Failed to create domain', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `domain` | `AzionCreateDomain` | O objeto de domínio contendo suas configurações. |
| `options` | `{ debug?: boolean }` | Opcional. O objeto contendo uma flag de debug para habilitar log detalhado. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDomain>>` | O objeto de domínio criado ou o erro em caso de falha. |

### `getDomains`

Este método lista todos os domínios. Exemplo:

```typescript
import { getDomains } from 'azion/domains';
import type { AzionDomainCollection, AzionDomainsResponse } from 'azion/domains';

const { data: domains, error }: AzionDomainsResponse<AzionDomainCollection> = await getDomains();

if (domains) {
  console.log(`Found ${domains.count} domains`);
} else {
  console.error('Failed to list domains', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `options` | `{ debug?: boolean }` | Opcional. O objeto contendo uma flag de debug para habilitar log detalhado. |
| `queryParams` | `{ pageSize?: number; page?: number; order?: 'id' \| 'name'; sort?: 'asc' \| 'desc' }` | Opcional. Parâmetros de query para paginação e ordenação. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDomainCollection>>` | Um array de objetos de domínio ou o erro em caso de falha. |

### `getDomain`

Use este método para obter um domínio pelo seu ID.

```typescript
import { getDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await getDomain(domainId);

if (domain) {
  console.log(`Found domain with name: ${domain.name}`);
} else {
  console.error('Failed to get domain', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `domainId` | `número` | O ID do domínio. |
| `options` | `{ debug?: boolean }` | Opcional. O objeto contendo uma flag de debug para habilitar log detalhado. |

### `updateDomain`

Este método atualiza um domínio.

```typescript
import { updateDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await updateDomain(domainId, {
  name: 'new domain name',
  edgeApplicationId: 456,
});

if (domain) {
  console.log(`Updated domain with name: ${domain.name}`);
} else {
  console.error('Failed to update domain', error);
}
```
**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `domainId` | `número` | O ID do domínio. |
| `domain` | `AzionUpdateDomain` | O objeto de domínio a ser atualizado. |
| `options` | `{ debug?: boolean }` | Opcional. O objeto contendo uma flag de debug para habilitar log detalhado. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDomain>>` | O objeto de domínio atualizado ou o estado de falha. |

### `deleteDomain`

Este método deleta um domínio especificado por seu ID.

```typescript
import { deleteDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 123;
const { data: deletedDomain, error }: AzionDomainsResponse<AzionDomain> = await deleteDomain(domainId);

if (deletedDomain) {
  console.log(`Deleted domain with ID: ${deletedDomain.id}`);
} else {
  console.error('Failed to delete domain', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `domainId` | `número` | O ID do domínio. |
| `options` | `{ debug?: boolean }` | Opcional. O objeto contendo uma flag de debug para habilitar log detalhado. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-------------|-------------|
| `Promise<AzionDomainsResponse<AzionDeletedDomain>>` | O ID do domínio deletado ou o estado de falha. |

---

## Tipos

Se você estiver usando **TypeScript**, precisará importar e usar os tipos adequados para os parâmetros e valores de retorno. Aqui você pode ver uma lista de todos os tipos usados pela biblioteca **Domains**:

### `AzionDomainsClient`

Opções de configuração para o cliente Azion Domains.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `token` | `string` | Opcional. Seu token de API Azion. |
| `options` | `OptionsParams` | Opcional. Objeto de opções de parâmetros. |
| `debug` | `boolean` | Opcional. Habilita o modo de debug para log detalhado. |

### `AzionDomainsResponse<T>`

Tipo de resposta genérico retornado por todos os métodos **Domains**.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `data` | `T` | Opcional. Os dados da resposta. |
| `error` | `{ message: string; operation: string; }` | Opcional. O objeto de erro. |

### `AzionDomain`

Representa a configuração de um domínio com suas propriedades.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `state` | `'pending' \| 'executed' \| 'failed'` | O estado do domínio. |
| `id` | `número` | Opcional. O ID do domínio. |
| `name` | `string` | O nome do domínio. |
| `url` | `string` | Opcional. A URL do domínio. |
| `environment` | `string` | Opcional. O ambiente do domínio. |
| `edgeApplicationId` | `número` | O ID da application. |
| `active` | `boolean` | O status do domínio. |
| `cnameAccessOnly` | `boolean` | Opcional. Acesso somente por CNAME. |
| `cnames` | `string[]` | Lista de CNAMEs. |
| `edgeFirewallId` | `número` | Opcional. O ID do firewall. |
| `digitalCertificateId` | `número \| string \| null` | O ID do certificado digital. |
| `mtls` | `object \| null` | Opcional. A configuração de TLS mútuo. |
| `mtls.verification` | `string` | Método de verificação: enforce ou permissive. |
| `mtls.trustedCaCertificateId` | `número` | O ID do certificado de CA confiável. |
| `mtls.crlList` | `number[]` | A lista de IDs de CRL. |

### `AzionDomainCollection`

Representa uma coleção de domínios com seu status atual e detalhes de paginação.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `state` | `'pending' \| 'executed' \| 'failed'` | O status da lista de domínios. |
| `pages` | `número` | Número de páginas. |
| `count` | `número` | Número de domínios. |
| `results` | `AzionDomain[]` | Array de objetos de domínio. |

### `AzionDeleteDomain`

Representa os parâmetros necessários para deletar um domínio.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `id` | `número` | O ID do domínio. |
| `state` | `'pending' \| 'executed' \| 'failed'` | O estado da exclusão do domínio. |