# Device groups

Um device group identifica dispositivos por uma expressão regular que a plataforma compara com o header de requisição `User-Agent`. Estas funções do `azion/applications` criam, listam, leem, atualizam e excluem os device groups de uma application.

---

## createDeviceGroup

Cria um device group em uma application. Um device group identifica dispositivos por uma expressão regular que a plataforma compara com o header de requisição `User-Agent`.

```typescript
function createDeviceGroup(params: {
  applicationId: number;
  data: ApiCreateDeviceGroupPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição                                                                                           |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.                                                                                |
| `data`          | `{ name: string; user_agent: string }`                                                               | Sim         | `name` dá nome ao grupo, e `user_agent` contém a expressão regular, como `Mobile\|Android\|iPhone`. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions) | Não         | Opções de requisição.                                                                               |

Retorna `data` como o [AzionDeviceGroup](/pt-br/documentacao/devtools/azion-lib/application/types/#aziondevicegroup) criado. A API recusa um `name` que contenha um espaço ou um hífen. A função então retorna `error` com a mensagem `HTTP error! Status: 400 - BAD REQUEST`.

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

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

// Create a new device group
const deviceGroupData = {
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone',
};

const { data: newDeviceGroup, error } = await createDeviceGroup({ applicationId, data: deviceGroupData });

if (error) {
  console.error('Error creating device group:', error);
} else {
  console.log('Device group created successfully:', newDeviceGroup);
}
```

Saída:

```text
Device group created successfully: {
  id: 1234,
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone'
}
```

---

## getDeviceGroups

Lista os device groups de uma application, uma página por vez.

```typescript
function getDeviceGroups(params: {
  applicationId: number;
  params?: ApiListDeviceGroupsParams;
  options?: AzionClientOptions;
}): Promise<AzionApplicationCollectionResponse<AzionDeviceGroup>>;
```

| Parâmetro       | Tipo                                                                                                         | Obrigatório | Descrição                        |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ----------- | -------------------------------- |
| `applicationId` | `number`                                                                                                     | Sim         | O ID da application.             |
| `params`        | [`ApiListDeviceGroupsParams`](/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 [AzionDeviceGroup](/pt-br/documentacao/devtools/azion-lib/application/types/#aziondevicegroup).

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

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

const { data: deviceGroups, error } = await getDeviceGroups({ applicationId, params: { page: 1, page_size: 20 } });

if (error) {
  console.error('Error listing device groups:', error);
} else {
  console.log(`Found ${deviceGroups?.count} device groups:`, deviceGroups?.results);
}
```

Saída:

```text
Found 1 device groups: [
  {
    id: 1234,
    name: 'MobileDevices',
    user_agent: 'Mobile|Android|iPhone'
  }
]
```

---

## getDeviceGroup

Retorna um device group de uma application pelo ID dele.

```typescript
function getDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição             |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | --------------------- |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.  |
| `deviceGroupId` | `number`                                                                                             | Sim         | O ID do device group. |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions) | Não         | Opções de requisição. |

Retorna `data` como um [AzionDeviceGroup](/pt-br/documentacao/devtools/azion-lib/application/types/#aziondevicegroup).

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

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { data: deviceGroup, error } = await getDeviceGroup({ applicationId, deviceGroupId });

if (error) {
  console.error('Error retrieving device group:', error);
} else {
  console.log('Device group details:', deviceGroup);
}
```

Saída:

```text
Device group details: {
  id: 1234,
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone'
}
```

---

## updateDeviceGroup

Envia em uma requisição `PATCH` os campos do device group que você passa. O novo `name` segue a mesma regra da criação: sem espaços e sem hífens.

```typescript
function updateDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  data: ApiUpdateDeviceGroupPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição                         |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | --------------------------------- |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.              |
| `deviceGroupId` | `number`                                                                                             | Sim         | O ID do device group a atualizar. |
| `data`          | `{ name?: string; user_agent?: string }`                                                             | Sim         | Os campos a mudar.                |
| `options`       | [`AzionClientOptions`](/pt-br/documentacao/devtools/azion-lib/application/types/#azionclientoptions) | Não         | Opções de requisição.             |

Retorna `data` como o [AzionDeviceGroup](/pt-br/documentacao/devtools/azion-lib/application/types/#aziondevicegroup) atualizado.

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

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { data: updatedDeviceGroup, error } = await updateDeviceGroup({
  applicationId,
  deviceGroupId,
  data: { name: 'MobileAndTablets', user_agent: 'Mobile|Android|iPhone|iPad' },
});

if (error) {
  console.error('Error updating device group:', error);
} else {
  console.log('Device group updated:', updatedDeviceGroup);
}
```

Saída:

```text
Device group updated: {
  id: 1234,
  name: 'MobileAndTablets',
  user_agent: 'Mobile|Android|iPhone|iPad'
}
```

---

## deleteDeviceGroup

Exclui um device group de uma application pelo ID dele.

```typescript
function deleteDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<void>>;
```

| Parâmetro       | Tipo                                                                                                 | Obrigatório | Descrição                       |
| --------------- | ---------------------------------------------------------------------------------------------------- | ----------- | ------------------------------- |
| `applicationId` | `number`                                                                                             | Sim         | O ID da application.            |
| `deviceGroupId` | `number`                                                                                             | Sim         | O ID do device group 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ê o device group de volta com [getDeviceGroup](#getdevicegroup). Um erro `404` confirma a exclusão.

```typescript
import { deleteDeviceGroup, getDeviceGroup } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { error: deleteError } = await deleteDeviceGroup({ applicationId, deviceGroupId });

// On success (HTTP 204) the envelope still carries an error, so confirm by reading it back
const { error } = await getDeviceGroup({ applicationId, deviceGroupId });
if (error) {
  console.log(`Device group ${deviceGroupId} deleted (read back: ${error.message})`);
} else {
  console.error('Error deleting device group:', deleteError);
}
```

Saída:

```text
Device group 1234 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.
- [Device groups](/pt-br/documentacao/plataforma/applications/device-groups.md): O device group que uma application identifica pelo User-Agent.