# Regras

Uma regra pertence ao Rules Engine de uma application, na fase de requisição ou na fase de resposta. Estas funções do `azion/applications` criam, listam, leem, atualizam e excluem essas regras, e cada uma recebe a fase como `phase`.

---

## createRule

Cria uma regra do Rules Engine de uma application, na fase de requisição ou na fase de resposta.

```typescript
function createRule(params: {
  applicationId: number;
  phase: "request" | "response";
  data: ApiCreateRulePayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionRule>>;
```

| Parâmetro       | Tipo                                                                                                     | Obrigatório | Descrição                                           |
| --------------- | -------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------- |
| `applicationId` | `number`                                                                                                 | Sim         | O ID da application.                                |
| `phase`         | `'request' \| 'response'`                                                                                | Sim         | A fase em que a regra é executada.                  |
| `data`          | [`ApiCreateRulePayload`](/pt-br/documentacao/devtools/azion-lib/application/types/#apicreaterulepayload) | Sim         | A regra: `name`, `phase`, `criteria` e `behaviors`. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions)     | Não         | Opções de requisição.                               |

`criteria` é uma lista de grupos de condições, e cada grupo é uma lista de condições com `variable`, `operator`, `conditional` e `input_value`. `behaviors` lista as ações, cada uma com um `name` e um `target`. Para as variáveis, os operadores e os nomes de behaviors que uma regra pode usar, consulte [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine/).

Retorna `data` como a [AzionRule](/pt-br/documentacao/devtools/azion-lib/application/types/#azionrule) criada, com o `id` e a `order` dela. No exemplo, `as const` mantém os tipos literais de que `phase` e `conditional` precisam no TypeScript.

```typescript
import { createRule } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

// Define the data for the new rule
const ruleData = {
  name: 'Example Rule',
  phase: 'request' as const,
  criteria: [[{ variable: '${uri}', operator: 'starts_with', conditional: 'if' as const, input_value: '/example-path' }]],
  behaviors: [{ name: 'redirect_to_301', target: 'https://example.com' }],
};

// Create a new rule in the request phase
const { data: newRule, error } = await createRule({ applicationId, phase: 'request', data: ruleData });

if (error) {
  console.error('Error creating rule:', error);
} else {
  console.log('Created rule:', JSON.stringify(newRule));
}
```

Saída:

```text
Created rule: {"id":123457,"name":"Example Rule","phase":"request","behaviors":[{"name":"redirect_to_301","target":"https://example.com"}],"criteria":[[{"variable":"${uri}","operator":"starts_with","conditional":"if","input_value":"/example-path"}]],"is_active":true,"order":1,"description":""}
```

---

## getRules

Lista as regras de uma fase de uma application, uma página por vez.

```typescript
function getRules(params: {
  applicationId: number;
  phase: "request" | "response";
  params?: ApiListRulesParams;
  options?: AzionClientOptions;
}): Promise<AzionApplicationCollectionResponse<AzionRule>>;
```

| Parâmetro       | Tipo                                                                                                  | Obrigatório | Descrição                        |
| --------------- | ----------------------------------------------------------------------------------------------------- | ----------- | -------------------------------- |
| `applicationId` | `number`                                                                                              | Sim         | O ID da application.             |
| `phase`         | `'request' \| 'response'`                                                                             | Sim         | A fase a listar.                 |
| `params`        | [`ApiListRulesParams`](/pt-br/documentacao/devtools/azion-lib/application/types/#parametros-de-lista) | Não         | Paginação: `page` e `page_size`. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions)  | Não         | Opções de requisição.            |

Retorna um [AzionApplicationCollectionResponse](/pt-br/documentacao/devtools/azion-lib/application/types/#azionapplicationcollectionresponse) cujo `data.results` contém objetos [AzionRule](/pt-br/documentacao/devtools/azion-lib/application/types/#azionrule). A lista de `request` também contém `Default Rule`, a regra da fase `default` que uma application já tem ao ser criada.

```typescript
import { getRules } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

const { data: rules, error } = await getRules({ applicationId, phase: 'request', params: { page: 1, page_size: 10 } });

if (error) {
  console.error('Error listing rules:', error);
} else {
  console.log(`Found ${rules?.count} rules:`, rules?.results.map((r) => `${r.id} ${r.name} (${r.phase}, order ${r.order})`));
}
```

Saída:

```text
Found 2 rules: [
  '123456 Default Rule (default, order 1)',
  '123457 Example Rule (request, order 1)'
]
```

---

## getRule

Retorna uma regra de uma application pela fase e pelo ID dela.

```typescript
function getRule(params: {
  applicationId: number;
  phase: "request" | "response";
  ruleId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionRule>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição             |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | --------------------- |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.  |
| `phase`         | `'request' \| 'response'`                                                                            | Sim         | A fase da regra.      |
| `ruleId`        | `number`                                                                                             | Sim         | O ID da regra.        |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions) | Não         | Opções de requisição. |

Retorna `data` como uma [AzionRule](/pt-br/documentacao/devtools/azion-lib/application/types/#azionrule).

```typescript
import { getRule } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const ruleId = 123457; // Replace with the actual rule ID

const { data: rule, error } = await getRule({ applicationId, phase: 'request', ruleId });

if (error) {
  console.error('Error retrieving rule:', error);
} else {
  console.log('Rule details:', JSON.stringify(rule));
}
```

Saída:

```text
Rule details: {"id":123457,"name":"Example Rule","phase":"request","behaviors":[{"name":"redirect_to_301","target":"https://example.com"}],"criteria":[[{"variable":"${uri}","operator":"starts_with","conditional":"if","input_value":"/example-path"}]],"is_active":true,"order":1,"description":""}
```

---

## updateRule

Envia em uma requisição `PATCH` os campos da regra que você passa. Os campos que você deixa de fora mantêm os valores: uma chamada que não envia `criteria` mantém os `criteria` da regra sem mudança.

```typescript
function updateRule(params: {
  applicationId: number;
  phase: "request" | "response";
  ruleId: number;
  data: ApiUpdateRulePayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionRule>>;
```

| Parâmetro       | Tipo                                                                                                     | Obrigatório | Descrição                                 |
| --------------- | -------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------- |
| `applicationId` | `number`                                                                                                 | Sim         | O ID da application.                      |
| `phase`         | `'request' \| 'response'`                                                                                | Sim         | A fase da regra.                          |
| `ruleId`        | `number`                                                                                                 | Sim         | O ID da regra a atualizar.                |
| `data`          | [`ApiUpdateRulePayload`](/pt-br/documentacao/devtools/azion-lib/application/types/#apicreaterulepayload) | Sim         | Os campos a mudar. Todo campo é opcional. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions)     | Não         | Opções de requisição.                     |

Retorna `data` como a [AzionRule](/pt-br/documentacao/devtools/azion-lib/application/types/#azionrule) atualizada.

```typescript
import { updateRule } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const ruleId = 123457; // Replace with the actual rule ID

const { data: updatedRule, error } = await updateRule({
  applicationId,
  phase: 'request',
  ruleId,
  data: { name: 'Example Rule Updated', behaviors: [{ name: 'redirect_to_302', target: 'https://example.com/new' }] },
});

if (error) {
  console.error('Error updating rule:', error);
} else {
  console.log('Updated rule:', JSON.stringify(updatedRule));
}
```

Saída:

```text
Updated rule: {"id":123457,"name":"Example Rule Updated","phase":"request","behaviors":[{"name":"redirect_to_302","target":"https://example.com/new"}],"criteria":[[{"variable":"${uri}","operator":"starts_with","conditional":"if","input_value":"/example-path"}]],"is_active":true,"order":1,"description":""}
```

---

## deleteRule

Exclui uma regra de uma application pela fase e pelo ID dela.

```typescript
function deleteRule(params: {
  applicationId: number;
  phase: "request" | "response";
  ruleId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<void>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição                |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | ------------------------ |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.     |
| `phase`         | `'request' \| 'response'`                                                                            | Sim         | A fase da regra.         |
| `ruleId`        | `number`                                                                                             | Sim         | O ID da regra a excluir. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions) | Não         | Opções de requisição.    |

Uma exclusão bem-sucedida retorna `error` com a mensagem `Expected JSON response, but got: `, por isso o exemplo lê a regra de volta com [getRule](#getrule). Um erro `404` confirma a exclusão.

```typescript
import { deleteRule, getRule } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const ruleId = 123457; // Replace with the actual rule ID

const { error: deleteError } = await deleteRule({ applicationId, phase: 'request', ruleId });

// On success (HTTP 204) the envelope still carries an error, so confirm by reading it back
const { error } = await getRule({ applicationId, phase: 'request', ruleId });
if (error) {
  console.log(`Rule ${ruleId} deleted (read back: ${error.message})`);
} else {
  console.error('Error deleting rule:', deleteError);
}
```

Saída:

```text
Rule 123457 deleted (read back: HTTP error! Status: 404 - NOT FOUND)
```

---

## Recursos relacionados

- [Azion Lib](/pt-br/documentacao/devtools/azion-lib.md): Os módulos da Azion Lib e o pacote npm em que cada um é distribuído.
- [Applications](/pt-br/documentacao/devtools/azion-lib/application.md): A autenticação do módulo, o envelope de resposta dele e os erros que as funções reportam.
- [Tipos de application](/pt-br/documentacao/devtools/azion-lib/application/types.md): Os tipos de payload e de resposta que estas funções recebem e retornam.
- [Rules Engine](/pt-br/documentacao/plataforma/applications/rules-engine.md): As fases de uma application e os critérios e behaviors que uma regra carrega.