コンテンツにスキップ

サイト更新

概要

APIを使用してサイト設定を更新することができます。

事前準備

APIの操作を行う前にAPIキーの作成を実施してください。また、この機能は「サイトの管理」権限をもつユーザでなければ使用できません。

リクエスト

下記のリクエスト形式で、jsonデータを送信します。

設定項目 値
HTTPメソッド POST
Content-Type application/json
文字コード UTF-8
URL http://{サーバ名}/api/items/{サイトID}/updatesite(※1)
Body 以下のjsonデータを参考のこと

(※1){サーバ名}、{サイトID}の部分は、適宜、環境に合わせて編集してください。
  pleasanter.netの場合は以下の形式になります。
  https://pleasanter.net/fs/api/items/{サイトID}/updatesite
  {サイトID}には、更新対象のサイトIDを指定してください。

JSON

{
    "ApiVersion": "1.1",
    "ApiKey": "345yuAjA6789dA09d8uj6...",
    "TenantId": 1,
    "Title": "サイト名",
    "ReferenceType": "Issues",
    "InheritPermission": 99999,
    "SiteSettings": {
        "Version": 1.017,
        "ReferenceType": "Issues",
        "GridColumns": [
            "IssueId",
            "TitleBody",
            "Comments",
            "StartTime",
            "CompletionTime",
            "WorkValue",
            "ProgressRate",
            "RemainingWorkValue",
            "Status",
            "Manager",
            "Owner",
            "Updator",
            "UpdatedTime"
        ],
        "EditorColumnHash": {
            "General": [
                "IssueId",
                "Ver",
                "Title",
                "Body",
                "StartTime",
                "CompletionTime",
                "WorkValue",
                "ProgressRate",
                "RemainingWorkValue",
                "Status",
                "Manager",
                "Owner",
                "Comments"
            ]
        }
    },
    "VerUp": true
}

※TenantID以降のパラメータについては、サイトパッケージをエクスポートした際の、"Site”パラメータと同等の値を設定してください。

Note

バージョン1.5.10.0以降は、AiProvidersのApiKeyにマスクした文字列********を指定すると、設定値は更新されません。

サンプルコード

Note

コード内の【 ... 】は適宜修正してください。

1. テンプレートのテーブルで直した画面の設定を、同じ種類の複数のテーブルへ配る

テンプレートのテーブルと、設定を配るテーブルをサイト取得APIで取得し、テンプレートと値が違う画面の設定(一覧の列・エディタの項目など)をテーブルごとに一覧にします。DRY_RUN = Falseにして実行すると、サイト更新APIで、各テーブルの画面の設定をテンプレートと同じにします。テーブルの名前とアクセス権の継承は、各テーブルの値のまま送ります。

実務での使いどころ

支店・拠点ごと、案件ごとに同じ形のテーブル(「問い合わせ管理」「点検記録」など)を並べて運用しているときに、本部がテンプレートで直した項目の並びや選択肢を、全てのテーブルへ同じ日に反映できます。サイトパッケージのインポートやサイトのコピーは新しいサイトを作る機能のため、運用中のテーブルの設定のみを差し替えることはできません。

事前準備

1:テンプレートのテーブルで、配りたい画面の設定(一覧・エディタ・項目の表示名・ビューなど)を直しておきます。

2:サンプルコードのBASE_URL・API_KEY・TEMPLATE_SITE_ID(テンプレートのサイトID)・TARGET_SITE_IDS(設定を配るテーブルのサイトID)を書き換えてください。APIキーは、テナント管理者のユーザで発行したものを使います。

3:まずDRY_RUN = Trueのまま実行して一覧を確かめ、Falseにして実行します。

Python
# ==========================================================
# テンプレートの設定を配る:テンプレートのテーブルで直した画面の設定(SiteSettings)を、
# 同じ種類の複数のテーブルへ、サイト更新API(updatesite)でまとめて配るサンプルです。
#
# テンプレートと各テーブルをサイト取得API(getsite)で取得し、テンプレートと値が違う
# SiteSettings のキー(GridColumns・EditorColumnHash など)をテーブルごとに表示します。
# 送るときは、TenantId・Title・ReferenceType・InheritPermission に各テーブルの値を使い、
# SiteSettings だけをテンプレートの値にします。
#
# 【注意】
#   ・APIキーはテナント管理者のユーザーで発行したものを使用してください。
#   ・まず DRY_RUN = True で一覧を確認してから、False にして実行してください。
#   ・リンク・ルックアップの参照先やスクリプトの中のサイトIDなど、テーブルごとに違う値に
#     したい設定も、テンプレートの値がそのまま配られます。
# ==========================================================
import json
import re

import requests

# ===== 設定 =====
BASE_URL = "【URL】"
API_KEY = "【APIキー】"
TEMPLATE_SITE_ID = 100              # テンプレートのテーブルのサイトID
TARGET_SITE_IDS = [101, 102, 103]   # 設定を配るテーブルのサイトID

# True の場合、何も送らず、テーブルごとの「テンプレートと値が違うキー」の一覧だけを表示する
DRY_RUN = True
# True の場合、VerUp を送り、新しいバージョンで保存する(1.5.6.0 より前の版では False にする)
VER_UP = True

TABLE_TYPES = ("Issues", "Results")  # 期限付きテーブル・記録テーブル
KEEP_KEYS = ("TenantId", "Title", "ReferenceType", "InheritPermission")  # 各テーブルの値を使うキー


def post(path, payload=None):
    body = {"ApiVersion": 1.1, "ApiKey": API_KEY}
    body.update(payload or {})
    return requests.post(
        f"{BASE_URL}/api/items/{path}",
        json=body,
        headers={"Content-Type": "application/json"},
        timeout=60,
    )


def get_site(site_id):
    """サイト取得APIでサイトを取得する。取得できなければ None とメッセージを返す"""
    response = post(f"{site_id}/getsite")
    if response.status_code != 200:
        try:
            message = response.json().get("Message", "")
        except ValueError:
            message = ""
        return None, message or f"HTTP {response.status_code}"
    return response.json()["Response"]["Data"], ""


def changed_keys(current, template):
    """SiteSettings のうち、テンプレートと値が違うキーを返す"""
    return sorted(k for k in set(current) | set(template) if current.get(k) != template.get(k))


def build_body(site, settings):
    body = {k: site.get(k) for k in KEEP_KEYS}
    body["SiteSettings"] = settings
    if VER_UP:
        body["VerUp"] = True
    return body


def warn_own_site_id(settings):
    """テンプレート自身のサイトIDと同じ数字が設定の中にあれば、注意を表示する"""
    text = json.dumps(settings, ensure_ascii=False)
    if re.search(rf"(?<!\d){TEMPLATE_SITE_ID}(?!\d)", text):
        print(f"[注意] テンプレートの設定に、テンプレート自身のサイトID({TEMPLATE_SITE_ID})と同じ数字があります。"
              "各テーブルにもそのまま配られます。")


def apply_to(site_id, template, settings, seen):
    """1つのテーブルを処理し、結果(更新・更新予定・変更なし・飛ばした・失敗)を返す"""
    if site_id == TEMPLATE_SITE_ID or site_id in seen:
        print(f"[飛ばした] {site_id}:{'テンプレート自身' if site_id == TEMPLATE_SITE_ID else '重複'}")
        return "飛ばした"
    seen.add(site_id)
    site, message = get_site(site_id)
    if site is None:
        print(f"[飛ばした] {site_id}:取得できません({message})")
        return "飛ばした"
    if site.get("ReferenceType") != template["ReferenceType"]:
        print(f"[飛ばした] {site_id}「{site.get('Title')}」:種類が違う({site.get('ReferenceType')})")
        return "飛ばした"
    keys = changed_keys(site.get("SiteSettings") or {}, settings)
    if not keys:
        print(f"[変更なし] {site_id}「{site['Title']}」")
        return "変更なし"
    print(f"[{'更新予定' if DRY_RUN else '更新'}] {site_id}「{site['Title']}」:{', '.join(keys)}")
    if DRY_RUN:
        return "更新予定"
    response = post(f"{site_id}/updatesite", build_body(site, settings))
    if response.status_code != 200:
        print(f"[失敗] {site_id}:HTTP {response.status_code} {response.text[:200]}")
        return "失敗"
    return "更新"


def main():
    template, message = get_site(TEMPLATE_SITE_ID)
    if template is None or template.get("ReferenceType") not in TABLE_TYPES:
        raise SystemExit(f"テンプレート({TEMPLATE_SITE_ID})を取得できないか、テーブルではありません。{message}")
    settings = template.get("SiteSettings") or {}
    print(f"テンプレート:{TEMPLATE_SITE_ID}「{template['Title']}」({template['ReferenceType']})")
    warn_own_site_id(settings)
    counts = dict.fromkeys(("更新", "更新予定", "変更なし", "飛ばした", "失敗"), 0)
    seen = set()
    for site_id in TARGET_SITE_IDS:
        counts[apply_to(site_id, template, settings, seen)] += 1
    print("、".join(f"{k} {v} 件" for k, v in counts.items()))
    return counts


if __name__ == "__main__":
    main()

表示の例(DRY_RUN = True)

テンプレート:100「課題管理(テンプレート)」(Issues)
[更新予定] 101「課題管理(東京支店)」:Columns, EditorColumnHash, GridColumns
[変更なし] 102「課題管理(大阪支店)」
[飛ばした] 103「点検記録(東京支店)」:種類が違う(Results)
更新 0 件、更新予定 1 件、変更なし 1 件、飛ばした 1 件、失敗 0 件

注記

  • 送るのは、テーブルの名前・種類・アクセス権の継承(各テーブルの値)と、画面の設定(テンプレートの値)です。テーブルの説明やアクセス権は送りません。
  • 種類(期限付きテーブル・記録テーブル)がテンプレートと違うテーブル、テンプレート自身、重複したサイトID、取得できないサイトIDは、送らずに理由を表示します。
  • リンク・ルックアップの参照先や、スクリプトの中のサイトIDなど、テーブルごとに違う値にしたい設定も、テンプレートの値がそのまま配られます。テンプレートの設定の中にテンプレート自身のサイトIDと同じ数字があるときは、最初に「[注意]」を表示します。
  • VerUpは1.5.6.0以降で使えます。それより前のバージョンでは、VER_UP = Falseにしてください。

対応バージョン

対応バージョン 内容
1.3.4.0 以降 機能追加
1.5.6.0 以降 VerUpを追加
1.5.10.0 以降 AI連携のAPIキー(ApiKey)がマスクした文字列の場合は、保存済みのAPIキーを使うよう変更