GoMSGraph

GoMSGraph は、Microsoft Graph API を簡単に利用するための Go 言語ライブラリです。
Azure AD アプリケーションを用いた認証処理から、ドライブアイテム(フォルダ/ファイル)の操作、SharePoint サイトの検索、大容量ファイルアップロードなどをシンプルなメソッドで実行できます。

特徴

認証処理の簡略化
Azure SDK の azidentity を利用し、Microsoft Graph API への認証をシンプルに実装。
GetAppToken メソッドを通じてアクセストークンを容易に取得可能です。
ドライブ操作
- フォルダの作成: CreateFolder メソッドで指定のドライブにフォルダを作成
- ルートアイテム一覧の取得: GetDriveRootItems メソッドでドライブのルートアイテムを取得
- アイテム削除: DeleteDriveItem メソッドで任意のアイテム (ファイル/フォルダ) を削除
サイト検索
指定したサイト名で、Microsoft 365 内のサイトを検索する GetSiteByName メソッドを提供。
大容量ファイルアップロード
アップロードセッションを作成する CreateUploadSession と、
セッションを使った分割アップロードの UploadFile メソッドで、大容量ファイルの取り扱いに対応。
カスタムロガー対応
デフォルトロガーにはUber Zapを用いており、必要に応じてカスタムロガーの差し替えが可能です。

ディレクトリ構成

ライブラリ内の主なファイル構成は以下の通りです。

graphhelper
├── client.go
├── drive_folder.go
├── drive_folder_test.go
├── drive_items.go
├── drive_items_test.go
├── fetch_app_token.go
├── fetch_app_token_test.go
├── fetch_sites.go
├── fetch_sites_test.go
├── upload_drive.go
├── upload_drive_session.go
├── upload_drive_session_test.go
├── upload_drive_test.go
└── zaplogger.go

service
└── grahpservice.go

必要条件

Go 1.18 以上
Microsoft Graph API へのアクセス権を持つ Azure アプリケーション (以下を取得済みであること)
- クライアント ID (AZURE_CLIENT_ID)
- テナント ID (AZURE_TENANT_ID)
- クライアントシークレット (AZURE_CLIENT_SECRET)
Microsoft Graph API で使用するスコープ： https://graph.microsoft.com/.default
操作対象の OneDrive または SharePoint ドライブ ID (DRIVE_ID)
※ ルートフォルダ以外を指定したい場合は、そのアイテムID (DRIVE_ROOT_ITEM_ID) も必要です。

インストール

Go Modules を使っているプロジェクトにて、以下のコマンドを実行してください。

go get github.com/Tsubasa-2005/GoMSGraph

環境変数の設定

このライブラリを使用するには、認証情報やドライブ情報を環境変数で設定します。

AZURE_CLIENT_ID
Azure AD アプリのクライアント ID
AZURE_TENANT_ID
Azure テナント ID
AZURE_CLIENT_SECRET
Azure AD アプリのクライアントシークレット
DRIVE_ID
操作対象となるドライブ ID
DRIVE_ROOT_ITEM_ID
ルートフォルダや任意フォルダのアイテム ID (フォルダ作成時の親 ID などに利用)

例:

export AZURE_CLIENT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export AZURE_TENANT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export AZURE_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxx"
export DRIVE_ID="xxxxxxxxxxxxxxxxxxxx"
export DRIVE_ROOT_ITEM_ID="xxxxxxxxxxxxxxxxxxxx"

使い方

以下は、本ライブラリの主な機能を利用するためのサンプルコード例です。
example.go

主なメソッド一覧

認証 / トークン取得
- GetAppToken(ctx context.Context) (azcore.AccessToken, error)
  アプリケーション権限で Microsoft Graph へアクセスするためのアクセストークンを取得します。
ドライブ操作
- CreateFolder(ctx context.Context, driveID, driveItemID, folderName string) (models.DriveItemable, error)
  ドライブ内で指定したフォルダID(またはルートID)の下に新たなフォルダを作成します。
- GetDriveRootItems(ctx context.Context, driveID string) ([]models.DriveItemable, error)
  指定ドライブのルートに含まれるアイテムを取得します。
- GetDriveItem(ctx context.Context, driveID, driveItemID string) (models.DriveItemable, error)
  指定したドライブアイテムの詳細情報を取得します。
- DeleteDriveItem(ctx context.Context, driveID, driveItemID string) error
  指定したアイテムを削除します。
- DownloadDriveItem(ctx context.Context, driveID, driveItemID string) ([]byte, error)
  ファイルの場合、コンテンツをダウンロードします。フォルダの場合はエラーが返されます。
サイト検索
- GetSiteByName(ctx context.Context, siteName string) ([]models.Siteable, error)
  サイト名を検索して一致する SharePoint サイトを返します。
大容量ファイルアップロード
- CreateUploadSession(ctx context.Context, driveID, itemPath string) (models.UploadSessionable, error)
  アップロードセッションを作成し、大容量ファイルの分割アップロードを可能にします。
- UploadFile(uploadSession models.UploadSessionable, file *os.File) (models.DriveItemable, error)
  取得したアップロードセッションを用いてファイルを分割アップロードします。

ドメインレベルの処理 (service パッケージ)

graphhelper パッケージは、Microsoft Graph API への各種リクエストをシンプルなラッパー関数として提供しています。一方、ビジネスロジックやドメイン固有の検証は service パッケージで実装されています。
この設計により、低レベルな API 呼び出しとドメインロジックの分離が実現され、利用者はシンプルなインターフェースを通じて各種機能を利用できるようになっています。

サンプルコード (DownloadDriveItem の場合)

func (s *graphServiceImpl) DownloadDriveItem(ctx context.Context, driveID, driveItemID string) ([]byte, error) {
    // まず対象のドライブアイテムを取得
    item, err := s.helper.GetDriveItem(ctx, driveID, driveItemID)
    if err != nil {
        return nil, fmt.Errorf("failed to retrieve drive item: %w", err)
    }
    // ファイルかどうかチェック（フォルダの場合は GetFile() が nil となる）
    if item.GetFile() == nil {
        return nil, fmt.Errorf("download is only supported for files, not folders")
    }
    // ファイルの場合のみダウンロード処理を実行
    return s.helper.DownloadDriveItem(ctx, driveID, driveItemID)
}

注意点

Microsoft Graph の仕様変更や、依存ライブラリの更新により、インターフェースや挙動が変わる場合があります。
大容量ファイルアップロード時には、ネットワーク切断やセッションの有効期限切れに注意が必要です。本ライブラリでは再開機能を含む実装を行っていますが、必ずしもすべてのケースをカバーできる保証はありません。

ライセンス

このライブラリは MIT License で公開されています。詳細は LICENSE ファイルをご確認ください。

貢献・お問い合わせ

バグ報告や新機能追加などの要望は、Issue や Pull Request で歓迎します。
ご質問やご不明点がありましたら、GitHub の Issue を通じてお知らせください。

# README