Data & Operations
This section provides detailed references for queries that retrieve operational data such as backups, logs, and analytics. These queries are essential for monitoring the health and activity of your Blocklet Server and its blocklets. For actions that modify this data, such as creating backups, please see the Mutations for Data & Operations.
Backups#
Retrieve backup history and summaries to monitor data protection status.
getBlockletBackups#
Fetches a list of backup records for a specific blocklet, optionally filtered by a time range.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet to retrieve backups for. |
|
| Optional. The start of the time range in ISO 8601 format (e.g., |
|
| Optional. The end of the time range in ISO 8601 format (e.g., |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getBlockletBackups({
input: {
did: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
startTime: '2023-01-01T00:00:00Z',
},
});
console.log('Backup Records:', result.backups);
} catch (error) {
console.error('Error fetching blocklet backups:', error.message);
}Example Response
{
"code": "ok",
"backups": [
{
"appPid": "z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j",
"userDid": "z1uX9z...",
"strategy": 0,
"target": "disk",
"targetName": "local-disk",
"targetUrl": "/mnt/data/backups/z8iZ...i0j.zip",
"createdAt": 1672531200,
"updatedAt": 1672531200,
"status": 1,
"message": "Backup completed successfully",
"progress": 100,
"metadata": {}
}
]
}This example retrieves all backup records for the specified blocklet since the beginning of 2023. The response includes a list of backup objects, each detailing the status, target, and timing of a backup job.
getBlockletBackupSummary#
Retrieves a summary of backup successes and failures for a blocklet, grouped by date.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet. |
|
| Optional. The start of the time range in ISO 8601 format. |
|
| Optional. The end of the time range in ISO 8601 format. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getBlockletBackupSummary({
input: {
did: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
},
});
console.log('Backup Summary:', result.summary);
} catch (error) {
console.error('Error fetching backup summary:', error.message);
}Example Response
{
"code": "ok",
"summary": [
{
"date": "2023-10-26",
"successCount": 5,
"errorCount": 1
},
{
"date": "2023-10-27",
"successCount": 6,
"errorCount": 0
}
]
}This example fetches the daily backup summary for a blocklet. The response provides a list of objects, each containing the date and the count of successful and failed backups for that day.
getBlockletsFromBackup#
Lists blocklets that are available within a backup file, which is useful before performing a restoration.
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
// Note: This query typically requires context from a restore operation.
const result = await client.getBlockletsFromBackup();
console.log('Available blocklets in backup:', result.backups);
} catch (error) {
console.error('Error listing blocklets from backup:', error.message);
}Example Response
{
"code": "ok",
"backups": [
{
"appDid": "z2qa...",
"appPid": "z8iZp...y9p",
"name": "My Awesome Blocklet",
"createdAt": 1672531200
}
]
}This call inspects a backup source and returns a list of blocklet states found within it, including their DID, PID, and name.
Logs & Analytics#
Access audit trails and traffic data to monitor activity and performance.
getAuditLogs#
Fetches a paginated list of audit logs, which record significant events and user actions across the node.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Optional. Pagination settings (page, pageSize). |
|
| Optional. Filter logs by scope (e.g., a blocklet DID). |
|
| Optional. Filter logs by category (e.g., |
|
| Optional. A search string to filter by action or content text. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getAuditLogs({
input: {
category: 'blocklet',
paging: { pageSize: 5 },
},
});
console.log('Audit Logs:', result.list);
} catch (error) {
console.error('Error fetching audit logs:', error.message);
}Example Response
{
"code": "ok",
"list": [
{
"id": "...",
"scope": "z8iZp...y9p",
"category": "blocklet",
"action": "start",
"content": "User started blocklet 'My Awesome Blocklet'",
"actor": {
"did": "z1uX9z...",
"role": "owner",
"fullName": "Satoshi Nakamoto",
"avatar": "",
"source": "node"
},
"env": {
"browser": { "name": "Chrome", "version": "108.0.0" },
"os": { "name": "macOS", "version": "13.0" }
},
"createdAt": 1672531200,
"ip": "127.0.0.1",
"ua": "Mozilla/5.0..."
}
],
"paging": {
"total": 100,
"pageSize": 5,
"page": 1,
"pageCount": 20
}
}This query retrieves the first 5 audit log entries related to the 'blocklet' category, providing details on who performed what action, when, and from where.
getTrafficInsights#
Retrieves traffic analytics for a specific blocklet over a defined period.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet. |
|
| The start date for the analytics range (e.g., |
|
| The end date for the analytics range (e.g., |
|
| Optional. Pagination settings. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getTrafficInsights({
input: {
did: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
startDate: '2023-10-01',
endDate: '2023-10-31',
},
});
console.log('Traffic Insights:', result.list);
} catch (error) {
console.error('Error fetching traffic insights:', error.message);
}Example Response
{
"code": "ok",
"list": [
{
"did": "z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j",
"date": "2023-10-27",
"totalRequests": 15023,
"validRequests": 14980,
"uniqueVisitors": 1204,
"bandwidth": 536870912
}
],
"paging": {
"total": 31,
"pageSize": 50,
"page": 1,
"pageCount": 1
}
}This example fetches daily traffic statistics for a blocklet for the month of October 2023, including request counts, unique visitors, and bandwidth usage.
getNotificationSendLog#
Retrieves a log of notifications sent from the node or a specific blocklet, with various filtering options.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet that sent the notifications. |
|
| Optional. An array with two ISO 8601 strings for the start and end of the range. |
|
| Optional. Pagination settings. |
|
| Optional. Filter by source ( |
|
| Optional. Filter by one or more component DIDs. |
|
| Optional. Filter by severity levels ( |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getNotificationSendLog({
input: {
teamDid: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
severities: ['error', 'warning'],
paging: { pageSize: 10 },
},
});
console.log('Notification Send Logs:', result.list);
} catch (error) {
console.error('Error fetching notification logs:', error.message);
}Example Response
{
"code": "ok",
"list": [
{
"id": "...",
"sender": "z8iZp...y9p",
"title": "Component Start Failed",
"description": "Component 'API Service' failed to start.",
"createdAt": 1672531200,
"severity": "error",
"source": "system",
"receivers": [{ "receiver": "z1uX9z...", "read": false }]
}
],
"paging": {
"total": 5,
"pageSize": 10,
"page": 1,
"pageCount": 1
}
}This retrieves the 10 most recent notifications with 'error' or 'warning' severity sent by the specified blocklet.
getPassportLogs#
Retrieves a log of activities for a specific passport, such as creation, updates, or usage events.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet that issued the passport. |
|
| The ID of the passport to retrieve logs for. |
|
| Optional. Pagination settings. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getPassportLogs({
input: {
teamDid: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
query: { passportId: 'z3uX9z...' },
paging: { pageSize: 10 },
},
});
console.log('Passport Logs:', result.passportLogs);
} catch (error) {
console.error('Error fetching passport logs:', error.message);
}Example Response
{
"passportLogs": [
{
"id": 123,
"passportId": "z3uX9z...",
"action": "issue",
"operatorIp": "192.168.1.1",
"operatorUa": "Mozilla/5.0...",
"operatorDid": "z1uX9z...",
"metadata": { "source": "admin_panel" },
"createdAt": 1672531200
}
],
"paging": {
"total": 1,
"pageSize": 10,
"page": 1,
"pageCount": 1
}
}This query fetches the activity log for a single passport, providing an audit trail of its lifecycle events.
getRelatedPassports#
Fetches a list of passports that are related to a given passport, typically those issued to the same user.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The DID of the blocklet that issued the passport. |
|
| The ID of the passport to find related passports for. |
|
| Optional. Pagination settings. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getRelatedPassports({
input: {
teamDid: 'z8iZpydA4aQf9pZ6a3j2a6b2c8d7e4f5g3h1i0j',
passportId: 'z3uX9z...',
},
});
console.log('Related Passports:', result.passports);
} catch (error) {
console.error('Error fetching related passports:', error.message);
}Example Response
{
"code": "ok",
"passports": [
{
"id": "z4uX9z...",
"name": "Another Passport",
"title": "Another Team Member",
"userDid": "z1uX9z...",
"status": "active",
"role": "guest"
}
],
"paging": {
"total": 1,
"pageSize": 10,
"page": 1,
"pageCount": 1
}
}This query is useful for understanding all the roles and access a single user has within a blocklet's ecosystem by finding all passports associated with their DID.
Sessions#
getLauncherSession#
Retrieves details about a specific launcher session, typically used during the blocklet installation process.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The unique ID of the launcher session. |
|
| The URL of the launcher service. |
Example
import BlockletServerClient from '@blocklet/server-js';
const client = new BlockletServerClient();
try {
const result = await client.getLauncherSession({
input: {
launcherSessionId: 'ls_1234567890abcdef',
launcherUrl: 'https://launcher.arcblock.io',
},
});
console.log('Launcher Session:', result.launcherSession);
} catch (error) {
console.error('Error fetching launcher session:', error.message);
}Example Response
{
"code": "ok",
"error": null,
"launcherSession": {
"id": "ls_1234567890abcdef",
"status": "completed",
"target": {
"blockletDid": "z8iZp...y9p"
},
"createdAt": "2023-10-27T10:00:00.000Z"
}
}This query fetches the state and details of a specific session from the launcher service, which is useful for tracking the progress of an installation initiated via the launcher.