GROWI REST API v3 × Pythonで簡単記事投稿！実践チュートリアル付き

はじめに

こんにちは、エンジニアの増井です。
業務でGROWIAPIを触る機会があったのですが調べてもGROWI REST API v1の記事が多くGROWI REST API v3について書かれている記事が少なかったので備忘録を兼ねてGROWI REST API v3を使って記事を作成する方法をまとめていこうと思います。

そもそもGROWIとは

GROWI（グローウィ）は、オープンソースのWikiツールで、情報共有やナレッジマネジメントを効率化するために社内Wikiとして活用されていてGrezzoでは以下のような用途で使用しています。

業務マニュアルや手順書の整備・管理
プロジェクトごとのドキュメント共有
社内ルール・FAQの一元管理

マークダウン記法に対応しており、直感的に文書を作成できるほか、ページの階層管理や全文検索機能により、必要な情報にすばやくアクセスできます。

動作環境

Python3.12.1
GROWI7.1.0
GROWI REST API v3 (7.2.6-RC.0)(https://docs.growi.org/en/api/rest-v3.html)

事前準備

GROWI側の準備

GROWIではAPIを使用するのにAPITokenを取得する必要があります。
GROWIにログインしてユーザー設定を開きAPI設定タブをクリックするとAPIToken更新ボタンがあるのでボタンをクリックします。

この時URLとしてエンコードできない文字(+や/)が含まれているとAPIを使用したときにエラーが返ってきてしまうので含まれない文字列になるまで更新ボタンを押してください。

Python側の準備

Python側ではRequestsモジュールのインストールをします。
requestsをpipからインストールします。pip install requests

ディレクトリ構造

root/
┠ GrowiApi.py
┠ CreatePageTest.py

サンプルコード

GrowiApi.py

ページ作成に必要なAPIはhttps://サーバー名/_api/v3/pageになります。
このAPIを使う時に必要になるpayload(サンプルコードのdataの部分)は

body : 記事の本文(必須)
path : 作成したい記事の場所(必須)
grant : 公開設定
grantUserGroupIds : 公開設定を指定した時のグループID
pageTags : 記事につけることのできるタグ機能

の5つありますが、今回はページを作成するだけなので必須部分の記事の本文と作成したい記事の場所を引数で受けとり事前準備で取得したAPITokenもAPIを使うのに必須なので引数で受け取っています。

requests.post()を使ってHTTPリクエストを送る

必要な情報は準備できたので実際にHTTPリクエストを送る部分の作成をします。
requests.postの引数に

APIToken
https://サーバー名/_api/v3/page
記事の本文と作成したい記事の場所

を渡すことで記事の作成をすることができます。
また、Responseのstatus_codeで作成が成功したか失敗したかが返ってきます。201なら成功、それ以外なら失敗という事になります。

import requests
import json

# GrowiAPIのエラーを表す例外クラス
class GrowiAPIError(Exception):
    def __init__(self, description):
        super().__init__()
        self.description = description
    
    def __repr__(self):
        return str(self.description)

    def __str__(self):
        return str(self.description)
    
# ページ作成
# Args :
#   url : GrowiのURL
#   access_token : APIトークン
#   body : ページの内容
#   path : 作成するページのパス
def CreatePage(url: str, accessToken: str, body: str, path: str) -> None:
    # エンドポイントの作成
    apiEndPoint = f'{url}/_api/v3/page'
    # アクセストークン
    params = {
        'access_token': accessToken,
    }
    # POSTするjsonデータの作成
    data = {
        'body': body,
        'path': path,
    }
    
    res = requests.post(apiEndPoint, data=data, params=params)
    print(f'response_code: {res.status_code}')

    # Responsesが正しく返ってきているかの確認
    if res.status_code == 201:
        return json.loads(res.text)
    else:
        raise GrowiAPIError(res.text)

CreatePageTest.py

サーバー名とアクセストークンはご自身の環境に沿って変更してください。
作成したい記事の場所をpathに記事の本文をbodyに入れて先ほど作成した関数に渡すだけの作りになっています。
res['page']['_id']で作成した記事のIDが取得できるので実際に作成した記事と同じか見るために記載しています。

import GrowiAPI

# GrowiのURLとAPIトークン
url = 'http://サーバー名'
accessToken = '取得したアクセストークン'

# 記事の作成
print('記事の作成')
path = '/user/ユーザー名/GrowiAPITest/テスト作成'
body = ('# APIで作成したページ')
res = GrowiAPI.CreatePage(url, accessToken, body, path)
print(f'ページのID : {res['page']['_id']}')
print('\n---')

実行結果

実装ができたので実際に実行してページが作成できたか確認していきます。
reatePageTest.pyのpath設定で/user/ユーザー名/GrowiAPITest/テスト作成として作成したのでGrowiAPITest以下にテスト作成という記事が作成されています。

また、ページIDもCrearePageTest.pyのprint(f"ページのID : {res['page']['_id']}")で出力された6852347d1945d039a8086bebと同じになっているのでAPIを使って記事の作成をすることができました。

おまけ

記事の詳細情報取得、記事の更新を説明は省きますがサンプルコードを載せておきます。

# 記事の詳細情報取得
# Args :
#     url : GrowiのURL
#     accessToken : APIトークン
#     pageId : 取得する記事のID
# Returns:
#     dict : 記事の詳細情報
def GetPageInfo(url: str, accessToken: str, pageId: str) -> dict:
    apiEndpoint = f'{url}/_api/v3/page'

    params = {
        'access_token': accessToken,
        'pageId': pageId,
    }

    res = requests.get(apiEndpoint, params=params)
    print(f'response_code: {res.status_code}')

    if res.status_code == 200:
        return json.loads(res.text)
    else:
        raise GrowiAPIError(res.text)
    
# 記事の更新
# Args :
#     url : GrowiのURL
#     accessToken : APIトークン
#     pageId : 取得する記事のID
#     revisionId : 取得する記事のリビジョンID
#     body : ページの内容
def UpdatePage(url: str, accessToken: str, pageId: str, revisionId: str ,body: str) -> None:
    apiEndpoint = f'{url}/_api/v3/page'
    params = {
        'access_token': accessToken,
    }
    
    data = {
        'pageId': pageId,
        'revisionId': revisionId,
        'body': body,
    }

    res = requests.put(apiEndpoint, data=data, params=params)
    print(f'response_code: {res.status_code}')

    if res.status_code == 201:
        return json.loads(res.text)
    else:
        raise GrowiAPIError(res.text)

まとめ

今回は、PythonとGROWI Rest API v3を使ってGROWI記事の作成をAPIからしました。
ここで紹介したAPI以外にも記事の削除、記事のいいね数、取得ユーザー設定の変更などもできるので他の機能を使ってみたい方は下記リンクにリファレンスがあるので活用してみてください！！

お知らせ

株式会社グレッゾではエンジニアを募集しております！
もしご興味がありましたら是非、下記リンクより応募よろしくお願いします。
https://www.grezzo.co.jp/jp/careers/