[comment]: # aside:2

[comment]: # ({e4e166a4-ebcec779})
# Guia de início rápido

Depois de [instalar](/devel/python/installation) o zabbix\_utils, você pode usá-lo em seu script.

Este guia de início rápido mostra como:

-   Recuperar o nome do host do agent Zabbix.
-   Criar um host e um item trapper usando a API do Zabbix.
-   Enviar um valor para o item.

O guia apresenta o script passo a passo, explicando cada parte à medida que é introduzida.
O [script completo](#complete-script) é fornecido ao final da página.

O guia também assume que seu server, agent e API do Zabbix estão sendo executados localmente.

[comment]: # ({/e4e166a4-ebcec779})

[comment]: # ({8ff8a246-7917ae33})
#### Recuperar o nome do host do agent Zabbix

Comece recuperando o nome do host do sistema onde o agent Zabbix está em execução.
Você precisará desse nome de host para criar um host usando a API do Zabbix.

1\. Importe a classe `Getter` de zabbix\_utils.
Esta classe funciona como o [Zabbix get](/manual/concepts/get) e permite que você solicite dados do agent Zabbix.

2\. Crie uma instância de `Getter` que se conecta ao agent Zabbix local em `127.0.0.1` na porta `10050`.

3\. Chame o método `get()` na instância de `Getter` para solicitar o nome do host ao agent Zabbix.

-   O método `get()` recebe uma chave de item como parâmetro e envia uma solicitação ao agent Zabbix para esse item.
-   O método `get()` retorna um objeto, e o nome do host é armazenado no atributo `value` desse objeto.
-   [`system.hostname`](/manual/config/items/itemtypes/zabbix_agent#system.hostname) é uma chave interna do agent Zabbix que retorna o nome do host.

```python
from zabbix_utils import Getter

agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value
```

[comment]: # ({/8ff8a246-7917ae33})

[comment]: # ({8f96b279-7bec0e05})
#### Conecte-se e faça login na API do Zabbix

Em seguida, conecte-se à API do Zabbix.
Isso permite que seu script gerencie objetos do Zabbix, como hosts e items.

1\. Importe a classe `ZabbixAPI` de zabbix\_utils.

2\. Crie uma instância de `ZabbixAPI` e forneça a URL da interface web do Zabbix.

3\. Chame o método `login()` na instância de `ZabbixAPI` e forneça seu nome de usuário e senha.
A conta deve ter [permissão](/manual/web_interface/frontend_sections/users/user_roles#default-permissions) para acessar a API do Zabbix.

4\. Chame o método `logout()` para fechar a sessão após as operações da API.

```python
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# As operações da API vão aqui

api.logout()
```

[comment]: # ({/8f96b279-7bec0e05})

[comment]: # ({8776420b-6f1a3be3})
#### Criar host no Zabbix

Agora que você tem o nome do host do agent Zabbix e está conectado à API do Zabbix, pode criar um novo host no Zabbix.

1\. Chame o método da API [`host.create()`](/manual/api/reference/host/create) na instância `ZabbixAPI` e forneça os detalhes do host:

-   `host` - defina como a variável `hostname` que contém o nome do host recuperado do agent Zabbix.
-   `interfaces` - contém detalhes de conexão para o agent Zabbix que está em execução no host.
-   `groups` - contém pelo menos um grupo de hosts ao qual o host deve pertencer.

2\. Como a API do Zabbix retorna o ID do host recém-criado, salve esse ID na variável `host_id` para uso posterior.

3\. Imprima uma mensagem para confirmar que o host foi criado.

```python
api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Host '{hostname}' criado com ID {host_id}")
```

[comment]: # ({/8776420b-6f1a3be3})

[comment]: # ({14e2596a-b8e7e66c})
#### Criar novo item no Zabbix

Após criar um host, você pode adicionar um item a ele.

1\. Defina uma chave exclusiva para o item a ser criado.

2\. Chame o método [`item.create()`](/manual/api/reference/item/create) na instância `ZabbixAPI` e forneça os detalhes do item:

-   `hostid` - defina como a variável `host_id` contendo o ID do host que você acabou de criar.
-   `name` - um nome para o item.
-   `key_` - defina como a variável `item_key` que você acabou de definir.
-   `type` - defina como `2` ([item trapper](/manual/config/items/itemtypes/trapper)), necessário para receber valores enviados do seu script nas etapas seguintes.
-   `value_type` - defina como `3` (numérico sem sinal), o tipo de dado que este item armazena.

3\. Como a API do Zabbix retorna o ID do item recém-criado, salve este ID na variável `item_id` para uso posterior.

4\. Imprima uma mensagem para confirmar que o item foi criado.

```python
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3,
)

item_id = item['itemids'][0]

print(f"Item '{item_key}' criado com ID {item_id}")
```

[comment]: # ({/14e2596a-b8e7e66c})

[comment]: # ({6d0ff9a9-10296181})
#### Enviar valor para o host

Agora que você criou seu host e item, pode enviar dados para ele.

1\. Importe a classe `time` e aguarde alguns segundos antes de enviar os dados.
Isso garante que o Zabbix tenha processado totalmente seu novo host e item.

2\. Importe a classe `Sender` de zabbix\_utils.
Esta classe funciona como o [Zabbix sender](/manual/concepts/sender) e permite que seu script envie dados para o Zabbix.

3\. Crie uma instância de `Sender` que se conecta ao Zabbix server local em `127.0.0.1` na porta `10051`.

4\. Chame o método `send_value()` na instância de `Sender` para enviar um valor para o item do seu host e forneça estes detalhes:

-   `hostname` - defina como a variável `hostname` que contém o nome do host que você recuperou do Zabbix agent.
-   `item_key` - defina como a variável `item_key` que você acabou de definir anteriormente em seu script.
-   `1` - o valor a ser enviado.

4\. Imprima uma mensagem para confirmar que o valor foi enviado.

```python
import time
time.sleep(10)

from zabbix_utils import Sender

sender = Sender(server='127.0.0.1', port=10051)

response = sender.send_value(hostname, item_key, 1)

print(f"Sender response: {response}")
```

Após a execução bem-sucedida deste código, você deverá ver uma mensagem de sucesso indicando que o Zabbix recebeu seu valor:

```bash
Sender response: {"processed": 1, "failed": 0, "total": 1, "time": "0.000151", "chunk": 1}
```

Agora você também pode verificar sua interface web do Zabbix (*Monitoramento > [Últimos dados](/manual/web_interface/frontend_sections/monitoring/latest_data)*) para ver o valor.

[comment]: # ({/6d0ff9a9-10296181})

[comment]: # ({a620a163-3872741b})
#### Script completo

Abaixo está o script completo que combina todas as etapas: recuperando o nome do host, criando o host e o item usando a API do Zabbix e enviando dados para o Zabbix.

```python
import time
from zabbix_utils import Getter, ZabbixAPI, Sender

# Recupera o nome do host do agent Zabbix
agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value

# Conecta e faz login na API do Zabbix
api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# Cria o host no Zabbix
host = api.host.create(
    host=hostname,
    interfaces=[{
        'type': 1,
        'main': 1,
        'useip': 1,
        'ip': '127.0.0.1',
        'dns': '',
        'port': '10050',
    }],
    groups=[{'groupid': '2'}]
)

host_id = host['hostids'][0]

print(f"Host '{hostname}' criado com ID {host_id}")

# Cria o item no Zabbix
item_key = 'app.myservice.heartbeat'

item = api.item.create(
    hostid=host_id,
    name='App heartbeat',
    key_=item_key,
    type=2,
    value_type=3
)

item_id = item['itemids'][0]

print(f"Item '{item_key}' criado com ID {item_id}")

# Faz logout da API
api.logout()

# Aguarda o Zabbix processar o novo host
time.sleep(10)

# Envia valor para o host
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value(hostname, item_key, 1)

print(f"Resposta do sender: {response}")
```

[comment]: # ({/a620a163-3872741b})