Andreas Hilbig
4ec61ffba1
- Moved GraphQL query samples into a new `docs/queries` directory for better organization. - Added new queries and mutations, including `createHost.graphql` and `GetApiVersion.graphql`. - Introduced `mcp-config.yaml` and updated `docker-compose.yml` for MCP integration. - Updated IntelliJ `.idea/workspace.xml` settings to reflect project changes. - Added new how-to guides (`docs/howtos`) for permissions, tags, MCP integration, and schema usage. - Enhanced tests by updating file paths and improving sample data locations. - Refined permissions and host group structures in `zabbix-hostgroups.ts` and `resolvers.ts`.
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
## 📊 Schema and Schema Extension
|
|
|
|
### Main Schema Structure
|
|
|
|
The GraphQL schema is located in the `../../schema/` directory and consists of:
|
|
|
|
- `queries.graphql` - Query definitions (see detailed documentation in file comments)
|
|
- `mutations.graphql` - Mutation definitions (see detailed documentation in file comments)
|
|
- `devices.graphql` - Device-related types (see detailed documentation in file comments)
|
|
- `zabbix.graphql` - Zabbix-specific types (see detailed documentation in file comments)
|
|
- `device_value_commons.graphql` - Common value types (see detailed documentation in file comments)
|
|
- `api_commons.graphql` - Common API types and permission system (see detailed documentation in file comments)
|
|
- `extensions/` - Custom device type extensions
|
|
|
|
For comprehensive understanding of each operation, read the detailed comments in the respective schema files.
|
|
|
|
### Zabbix to GraphQL Mapping
|
|
|
|
The API maps Zabbix entities to GraphQL types as follows:
|
|
|
|
| Zabbix Entity | GraphQL Type | Description |
|
|
|---------------|--------------|-------------|
|
|
| Host | `Host` / `Device` | Represents a Zabbix host; `Device` is a specialized `Host` with a `deviceType` tag |
|
|
| Host Group | `HostGroup` | Represents a Zabbix host group |
|
|
| Template | `Template` | Represents a Zabbix template |
|
|
| Template Group | `HostGroup` | Represents a Zabbix template group |
|
|
| Item | Nested fields in `Device` | Zabbix items become nested fields in the device based on their key names |
|
|
| Tag | `Tag` | Represents a Zabbix tag associated with a host or template |
|
|
| Inventory | `Location` | Host inventory information maps to location data |
|
|
|
|
### Zabbix Entity Relationships
|
|
|
|
- **Host Groups**: Organize hosts and templates hierarchically; represented as `HostGroup` objects in GraphQL
|
|
- **Templates**: Contain items and other configuration that can be applied to hosts; linked via template groups
|
|
- **Items**: Individual metrics collected from hosts; automatically mapped to nested GraphQL fields based on their key names
|
|
- **Tags**: Metadata associated with hosts/templates; used for classification and filtering
|
|
|
|
### Location Type Usage
|
|
|
|
The `Location` type represents geographical information from Zabbix host inventory:
|
|
|
|
- **Fields**: Includes `name`, `location_lat`, `location_lon`, and other inventory attributes
|
|
- **Usage**: Available through the `locations` query and as part of host/device objects
|
|
- **Access**: Retrieved via the `getLocations` method in the Zabbix API datasource
|
|
|
|
### Dynamic Schema Extension
|
|
|
|
Extend the schema without code changes using environment variables:
|
|
|
|
```bash
|
|
ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
|
|
ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice
|
|
```
|
|
|
|
This enables runtime schema extension for custom device types without modifying the core code.
|
|
|
|
### Sample Operations
|
|
|
|
For practical examples of schema usage, see the sample files in the `../queries/` directory:
|
|
- `../queries/sample_all_devices_query.graphql` - Example of querying all devices
|
|
- `../queries/sample_import_templates_mutation.graphql` - Example of importing templates
|
|
- `../queries/sample_import_host_groups_mutation.graphql` - Example of importing host groups
|