line-works-board 0.1.1

LINE WORKS掲示板APIのPython SDK

LINE WORKS Board API SDK

LINE WORKS掲示板APIのPython SDKです。掲示板への投稿、コメント、更新、削除などの操作を簡単に行うことができます。

🚀 特徴

• 簡単な操作: シンプルなAPIで掲示板操作が可能
• 型安全: TypeHintによる型安全なコード
• JWT認証: LINE WORKS APIの公式認証方式をサポート
• 包括的: 投稿の作成・更新・削除・取得・検索をフルサポート
• エラーハンドリング: 詳細なエラー情報とステータスコード

📦 インストール

uv add line-works-board

🔧 セットアップ

1. LINE WORKS Developer Console設定

1. LINE WORKS Developer Consoleにアクセス
2. 新しいアプリを作成
3. 掲示板APIの権限（board, board.read）を有効化
4. クライアントID、クライアントシークレットを取得

2. サービスアカウント設定

1. LINE WORKS管理画面でサービスアカウントを作成
2. RSA秘密鍵を生成・ダウンロード
3. 秘密鍵をPEM形式で保存

3. 環境変数設定

.envファイルを作成（推奨）：

# .env
LINE_WORKS_CLIENT_ID=your_client_id
LINE_WORKS_CLIENT_SECRET=your_client_secret
LINE_WORKS_SERVICE_ACCOUNT=your_service_account@your-domain
LINE_WORKS_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"
LINE_WORKS_BOARD_ID=your_board_id
LINE_WORKS_DOMAIN=your-domain.worksmobile.com

🔥 クイックスタート

import os
from dotenv import load_dotenv
from line_works_board import Board, BoardBody, ComposeBody

# 環境変数を読み込み
load_dotenv()

# 掲示板設定
board_body = BoardBody(
    client_id=os.getenv('LINE_WORKS_CLIENT_ID'),
    client_secret=os.getenv('LINE_WORKS_CLIENT_SECRET'),
    service_account=os.getenv('LINE_WORKS_SERVICE_ACCOUNT'),
    private_key=os.getenv('LINE_WORKS_PRIVATE_KEY'),
    domain=os.getenv('LINE_WORKS_DOMAIN')
)

# 掲示板インスタンス作成
board = Board(board_body, os.getenv('LINE_WORKS_BOARD_ID'))

# 投稿作成
compose_body = ComposeBody(
    title="Hello, LINE WORKS!",
    body="これは最初の投稿です。",
    enableComment=True,
    sendNotifications=True
)

response = board.compose(compose_body)
if response.success:
    print(f"投稿作成成功！ID: {response.data.get('id')}")
else:
    print(f"エラー: {response.error}")

📖 使用方法

🗣️ 投稿の作成

from line_works_board.types import ComposeBody
from datetime import datetime, timedelta

# 通常の投稿
compose_body = ComposeBody(
    title="通常の投稿",
    body="投稿内容をここに書きます。",
    enableComment=True,        # コメント許可
    sendNotifications=True     # 通知送信
)

# 必読投稿（7日間）
end_date = (datetime.now() + timedelta(days=7)).strftime('%Y-%m-%d')
must_read_body = ComposeBody(
    title="【必読】重要なお知らせ",
    body="必ずお読みください。",
    mustReadEndDate=end_date,  # 必読終了日
    enableComment=False,       # コメント無効
    sendNotifications=True
)

response = board.compose(compose_body)

✏️ 投稿の更新

updated_body = ComposeBody(
    title="更新されたタイトル",
    body="更新された内容です。",
    enableComment=True,
    sendNotifications=False    # 更新通知は送信しない
)

response = board.modify(updated_body, post_id="YOUR_POST_ID")

💬 コメントの投稿

from line_works_board.types import ReplyBody

reply_body = ReplyBody(
    content="これはコメントです。"
)

response = board.reply(reply_body, post_id="YOUR_POST_ID")

🗑️ 投稿の削除

response = board.delete(post_id="YOUR_POST_ID")

📄 データの取得

# 特定の投稿を取得
post = board.get_post(post_id="YOUR_POST_ID")

# 投稿一覧を取得（最新20件）
posts = board.get_posts(limit=20, offset=0)

# コメント一覧を取得
comments = board.get_replies(post_id="YOUR_POST_ID", limit=10)

# 投稿を検索
results = board.search_posts(query="重要", limit=10)

# 掲示板情報を取得
board_info = board.get_board_info()

🔍 テストスクリプト

完全なテストスクリプトが含まれています：

# 認証テスト
cd src/example
uv run test_auth.py

# 投稿作成テスト
uv run compose_test.py

# 投稿更新テスト
uv run modify_posts.py

# 投稿削除テスト
uv run delete_posts.py

# コメント機能テスト
uv run reply_posts.py

# 統合テスト
uv run test_with_dotenv.py

📝 データ型

ComposeBody（投稿データ）

@dataclass
class ComposeBody:
    title: str                              # 件名（必須、1-200文字）
    body: str                               # 内容（必須、1-716800文字）
    enableComment: Optional[bool] = True    # コメント許可フラグ
    mustReadEndDate: Optional[str] = None   # 必読終了日（YYYY-MM-DD）
    sendNotifications: Optional[bool] = True # 投稿通知送信フラグ

ReplyBody（コメントデータ）

@dataclass
class ReplyBody:
    content: str                            # コメント内容（必須）
    attachments: Optional[List[Dict]] = None # 添付ファイル情報

ApiResponse（レスポンス）

@dataclass
class ApiResponse:
    success: bool                           # 成功フラグ
    data: Optional[Any] = None              # レスポンスデータ
    error: Optional[str] = None             # エラーメッセージ
    status_code: Optional[int] = None       # HTTPステータスコード

⚡ パフォーマンス

• JWT認証: 自動トークン管理・更新
• 効率的なリクエスト: 必要最小限のAPIコール
• エラー回復: 適切なリトライとエラーハンドリング

🛡️ エラーハンドリング

response = board.compose(compose_body)

if response.success:
    # 成功時
    post_id = response.data.get('id')
    print(f"投稿作成成功: {post_id}")
else:
    # エラー時
    print(f"エラーコード: {response.status_code}")
    print(f"エラー内容: {response.error}")
    
    # 具体的なエラー対応
    if response.status_code == 401:
        print("認証エラー: 設定を確認してください")
    elif response.status_code == 404:
        print("掲示板IDが見つかりません")
    elif response.status_code == 400:
        print("リクエストパラメータに問題があります")

🎯 対応機能

機能	メソッド	説明
✅ 投稿作成	compose()	新しい投稿を作成
✅ 投稿更新	modify()	既存の投稿を更新
✅ 投稿削除	delete()	投稿を削除
✅ 投稿取得	get_post()	特定の投稿を取得
✅ 投稿一覧	get_posts()	投稿一覧を取得
✅ コメント投稿	reply()	投稿にコメント
✅ コメント一覧	get_replies()	コメント一覧を取得
✅ 投稿検索	search_posts()	キーワードで投稿を検索
✅ 掲示板情報	get_board_info()	掲示板の基本情報を取得
✅ 認証テスト	test_auth()	認証状態をテスト

🔗 依存関係

[project]
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31.0",
    "PyJWT>=2.8.0",
    "cryptography>=41.0.0",
    "python-dotenv>=1.0.0",
]

📚 参考資料

• LINE WORKS Developer Guide
• LINE WORKS Board API
• JWT認証

🤝 コントリビューション

1. このリポジトリをフォーク
2. フィーチャーブランチを作成 (git checkout -b feature/AmazingFeature)
3. 変更をコミット (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュ (git push origin feature/AmazingFeature)
5. プルリクエストを作成

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルをご覧ください。

🆘 サポート

問題が発生した場合は、以下をお試しください：

1. 認証エラー: クライアントID、シークレット、秘密鍵の設定を確認
2. 404エラー: 掲示板IDが正しいか確認
3. 権限エラー: LINE WORKS管理画面でAPI権限が有効になっているか確認

💡 Tips

• .envファイルは.gitignoreに追加してリポジトリにコミットしないでください
• 秘密鍵は改行を含めて正確にコピーしてください
• 必読投稿の日付はYYYY-MM-DD形式で指定してください
• コメント無効の投稿にはコメントできません