SDK

Piora 提供官方 SDK，讓你能在應用程式中方便地整合 Piora API，無需直接處理 HTTP 請求。

官方 SDK

Node.js / TypeScript

npm install @piora/sdk

import { PioraClient } from '@piora/sdk';

const piora = new PioraClient({
  token: process.env.PIORA_API_TOKEN,
});

// 列出所有伺服器
const servers = await piora.servers.list();

// 取得應用詳情
const app = await piora.applications.get('app_xxxxxxxxxxxx');

// 觸發部署
const deployment = await piora.applications.deploy('app_xxxxxxxxxxxx', {
  branch: 'main',
});

Python

pip install piora-sdk

from piora import PioraClient

piora = PioraClient(token=os.environ['PIORA_API_TOKEN'])

# 列出所有伺服器
servers = piora.servers.list()

# 取得應用詳情
app = piora.applications.get('app_xxxxxxxxxxxx')

# 觸發部署
deployment = piora.applications.deploy('app_xxxxxxxxxxxx', branch='main')

SDK 功能

所有官方 SDK 都提供以下功能：

功能	說明
完整 API 覆蓋	支援所有 Piora API 端點
型別安全	TypeScript 完整型別定義
自動重試	暫時性錯誤自動重試
分頁輔助	自動處理分頁查詢
錯誤處理	結構化的錯誤類別

使用範例

管理伺服器

// 列出所有伺服器
const servers = await piora.servers.list();
for (const server of servers) {
  console.log(`${server.name}: ${server.status}`);
}

// 取得伺服器狀態
const stats = await piora.servers.stats('srv_xxxxxxxxxxxx');
console.log(`CPU: ${stats.cpu}%, Memory: ${stats.memory}%`);

管理應用

// 建立應用
const app = await piora.applications.create({
  name: 'my-new-app',
  serverId: 'srv_xxxxxxxxxxxx',
  source: {
    type: 'git',
    repository: 'https://github.com/user/repo',
    branch: 'main',
  },
});

// 設定環境變數
await piora.applications.setEnv('app_xxxxxxxxxxxx', {
  NODE_ENV: 'production',
  DATABASE_URL: 'postgresql://...',
});

// 部署
const deployment = await piora.applications.deploy('app_xxxxxxxxxxxx');

// 等待部署完成
await deployment.waitUntilComplete();
console.log('部署成功！');

管理資料庫

// 建立 PostgreSQL 資料庫
const db = await piora.databases.create({
  type: 'postgresql',
  version: '16',
  name: 'my-database',
  serverId: 'srv_xxxxxxxxxxxx',
});

// 取得連線資訊
const connectionInfo = await piora.databases.connectionInfo(db.id);
console.log(connectionInfo.url);

監聽 Webhook 事件

import { PioraWebhookHandler } from '@piora/sdk';

const handler = new PioraWebhookHandler({
  secret: process.env.PIORA_WEBHOOK_SECRET,
});

// Express.js 整合
app.post('/webhook', handler.express((event) => {
  switch (event.type) {
    case 'deployment.succeeded':
      console.log(`部署成功: ${event.data.application.name}`);
      break;
    case 'deployment.failed':
      console.log(`部署失敗: ${event.data.application.name}`);
      // 發送告警通知
      break;
  }
}));

錯誤處理

SDK 提供結構化的錯誤類別：

import { PioraError, AuthenticationError, NotFoundError } from '@piora/sdk';

try {
  const app = await piora.applications.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Token 無效或已過期');
  } else if (error instanceof NotFoundError) {
    console.error('找不到指定的應用');
  } else if (error instanceof PioraError) {
    console.error(`API 錯誤: ${error.code} - ${error.message}`);
  }
}

分頁處理

// 手動分頁
const page1 = await piora.applications.list({ page: 1, perPage: 20 });
const page2 = await piora.applications.list({ page: 2, perPage: 20 });

// 自動遍歷所有頁面
for await (const app of piora.applications.listAll()) {
  console.log(app.name);
}

社群 SDK

除了官方 SDK，社群也維護了以下語言的 SDK：

語言	套件名稱	維護者
Go	`github.com/piora-dev/piora-go`	社群
Ruby	`piora-ruby`	社群
PHP	`piora/sdk-php`	社群