GSS.Vital.BizForm.SDK 0.1.8

There is a newer version of this package available.
See the version list below for details.

dotnet add package GSS.Vital.BizForm.SDK --version 0.1.8

NuGet\Install-Package GSS.Vital.BizForm.SDK -Version 0.1.8

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="GSS.Vital.BizForm.SDK" Version="0.1.8" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add GSS.Vital.BizForm.SDK --version 0.1.8

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: GSS.Vital.BizForm.SDK, 0.1.8"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install GSS.Vital.BizForm.SDK as a Cake Addin
#addin nuget:?package=GSS.Vital.BizForm.SDK&version=0.1.8

// Install GSS.Vital.BizForm.SDK as a Cake Tool
#tool nuget:?package=GSS.Vital.BizForm.SDK&version=0.1.8

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

BizForm API .NET SDK

這是一個用於存取 VitalBizform 系統 API 的 .NET SDK，提供完整的 API 封裝，讓開發者能夠輕鬆地與 VitalBizform 系統進行互動。

系統需求

.NET 9.0 或更高版本
Visual Studio 2022 或更高版本
有效的 API 金鑰（請參考 API Key 產生說明）

安裝方式

使用 .NET CLI：

dotnet add package GSS.Vital.BizForm.SDK

或使用 Visual Studio 的 Package Manager Console：

Install-Package GSS.Vital.BizForm.SDK

快速開始

1. 設定方式

SDK 提供多種設定方式，依優先順序如下：

環境變數（最高優先）

# 必要設定
BIZFORM_API_BASE_URL=https://bizform.vikosmos.com/Backend/
BIZFORM_API_LOGIN_URL=https://member.vikosmos.com/cas/login
BIZFORM_API_TOKEN_URL=https://bizform.vikosmos.com/Backend/api/account/token
BIZFORM_USERNAME=your-username
BIZFORM_PASSWORD=your-password

# 選用設定
BIZFORM_BEARER_TOKEN=your-bearer-token
BIZFORM_API_KEY=your-api-key
BIZFORM_DEPOT_ID=your-depot-id
BIZFORM_TOKEN_REFRESH_MINUTES=10
BIZFORM_REQUEST_TIMEOUT_SECONDS=30

程式碼設定

services.AddBizFormSDK(options =>
{
    options.BaseUrl = "https://bizform.vikosmos.com/Backend/";
    options.LoginUrl = "https://member.vikosmos.com/cas/login";
    options.TokenUrl = "https://bizform.vikosmos.com/Backend/api/account/token";
    options.ClientId = "your-username";
    options.ClientSecret = "your-password";
    options.TokenRefreshMinutes = 10;
    options.RequestTimeoutSeconds = 30;
});

功能特點

核心功能

表單管理

建立、讀取、更新、刪除表單
批次處理功能
表單狀態追蹤
自定義表單欄位

提交管理

表單提交
提交記錄查詢
提交狀態追蹤
批次提交處理

檔案管理

檔案上傳/下載
檔案版本控制
檔案預覽
檔案權限管理

使用者管理

使用者認證
權限控制
角色管理
使用者邀請

技術特性

模組化設計：支援依賴注入，易於整合
非同步支援：全面的非同步操作支援
Token 管理：自動的 JWT Token 管理與更新
錯誤處理：統一的錯誤處理機制
日誌記錄：詳細的操作日誌
高度可測試：完整的單元測試支援

使用範例

表單管理

// 初始化服務
var bizFormService = serviceProvider.GetRequiredService<IBizFormService>();

// 取得表單列表
var forms = await bizFormService.GetFormsAsync(token);

使用者管理

// 取得使用者清單
var userListRequest = new UserListRequest 
{
    PageSize = 20,
    PageIndex = 0,
    Keyword = "john",
    OrderBy = "displayName",
    Enabled = true
};
var users = await bizFormService.GetUserListAsync(token, userListRequest);

// 邀請新使用者 (需要管理者權限)
bool success = await bizFormService.InviteUserAsync(
    token: "your-admin-token",
    email: "newuser@example.com"
);

錯誤處理

異常類型

ArgumentException：參數驗證失敗（如：電子郵件格式不正確）
HttpRequestException：API 請求失敗，包含詳細的錯誤訊息
InvalidOperationException：操作無效（如：API 回傳空值）
UnauthorizedAccessException：認證失敗或權限不足

錯誤處理範例

try
{
    // 呼叫 SDK 方法
    var users = await bizFormService.GetUserListAsync(token, request);
}
catch (ArgumentException ex)
{
    // 處理參數錯誤
    logger.LogError("參數錯誤: {Message}", ex.Message);
}
catch (HttpRequestException ex)
{
    // 處理 API 請求錯誤
    logger.LogError("API 請求失敗: {Message}", ex.Message);
}
catch (UnauthorizedAccessException ex)
{
    // 處理認證或權限錯誤
    logger.LogError("認證失敗: {Message}", ex.Message);
}
catch (Exception ex)
{
    // 處理其他未預期的錯誤
    logger.LogError("未預期的錯誤: {Message}", ex.Message);
}

API 功能說明

使用者管理 API

GetTokenAsync

Task<string> GetTokenAsync()

取得認證 Token。此 Token 用於後續 API 呼叫的身份驗證。

回傳：JWT Token 字串
錯誤：認證失敗時拋出異常

GetUserListAsync

Task<IEnumerable<User>> GetUserListAsync(string token)

取得系統中所有使用者清單。

參數：
- token：認證 Token
回傳：使用者清單
錯誤：權限不足或 Token 無效時拋出異常

GetUserAsync

Task<User> GetUserAsync(string token, string email)

取得單一使用者的詳細資訊。

參數：
- token：認證 Token
- email：要查詢的使用者電子郵件
回傳：
- User 物件：查詢成功時返回使用者資訊
- null：使用者不存在
錯誤：
- 電子郵件格式錯誤
- Token 無效

// 使用範例
var user = await bizFormService.GetUserAsync(token, "user@example.com");
if (user != null)
{
    Console.WriteLine($"使用者名稱: {user.DisplayName}");
    Console.WriteLine($"是否為管理者: {user.IsManager}");
    Console.WriteLine($"帳號狀態: {(user.Disabled ? "已停用" : "啟用中")}");
}

InviteUserAsync

Task<bool> InviteUserAsync(string token, string email)

邀請新使用者加入系統（需要管理者權限）。

參數：
- token：認證 Token
- email：被邀請者的電子郵件
回傳：
- true：邀請成功
- false：邀請失敗
錯誤：
- 電子郵件格式錯誤
- 權限不足
- Token 無效

DisableUserAsync

Task<bool> DisableUserAsync(string token, string email)

停用指定使用者的帳號（需要管理者權限）。

參數：
- token：認證 Token
- email：要停用的使用者電子郵件
回傳：
- true：停用成功
- false：使用者不存在
錯誤：
- 電子郵件格式錯誤
- 權限不足
- Token 無效

使用範例

// 取得 Token
var token = await bizFormService.GetTokenAsync();

// 取得使用者清單
var users = await bizFormService.GetUserListAsync(token);

// 邀請新使用者
var invited = await bizFormService.InviteUserAsync(token, "newuser@example.com");

// 停用使用者
var disabled = await bizFormService.DisableUserAsync(token, "user@example.com");

版本資訊

當前版本

版本號：0.0.2
發布日期：2024-12-24
支援的 .NET 版本：.NET 8.0+

更新記錄

1.0.1 (2024-12-13)
- 修正 Form 模型中的 Privileges 屬性型別
- 優化 JSON 反序列化處理
- 新增使用者管理功能
1.0.0 (2024-12-01)
- 初始版本發布
- 完整支援表單管理 API
- 整合 JWT 認證機制