コンテンツにスキップ

サイト取得

概要

APIを使用してサイト情報を取得することができます。

制限事項

  1. wikiには対応していません。
  2. 1.5.10.0

    取得するサイトの「サイトの管理権限」が無いユーザ(特権ユーザを除く)が実行した場合、SiteSettings(項目のラベルや選択肢などのサイトの設定)は取得できません。テナント管理者であっても、サイトの管理権限が無い場合は同じです。SiteIdやTitleなどのサイトの情報は取得できます。SiteSettingsを参照する処理では、値があることを確かめてから使用してください。

事前準備

APIの操作を行う前にAPIキーの作成を実施してください。また、この機能はテナント管理者でないと行えないため、ユーザ管理からテナント管理者の設定を行ってください。

リクエスト

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

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

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

JSON
{
    "ApiVersion": "1.1",
    "ApiKey": "345yuAjA6789dA09d8uj6..."
}

レスポンス

下記の形式のJSONデータが返却されます。

JSON
{
    "StatusCode": 200,
    "Response": {
        "Data": {
            "TenantId": 1,
            "SiteId": 12345,
            "UpdatedTime": "2023-08-17T12:00:00",
            "Ver": 1,
            "Title": "記録テーブル",
            "Body": "",
            "SiteName": "",
            "SiteGroupName": "",
            "GridGuide": "",
            "EditorGuide": "",
            "CalendarGuide": "",
            "CrosstabGuide": "",
            "GanttGuide": "",
            "BurnDownGuide": "",
            "TimeSeriesGuide": "",
            "KambanGuide": "",
            "ImageLibGuide": "",
            "ReferenceType": "Results",
            "ParentId": 12344,
            "InheritPermission": 3301,
            "Permissions": [
            ],
            "SiteSettings": {
                "Version": 1.017,
                "ReferenceType": "Results",
                "EditorColumnHash": {
                    "General": [
                        "ResultId",
                        "Ver",
                        "Title",
                        "Body",
                        "Status",
                        "Manager",
                        "Owner",
                        "Comments",
                        "ClassA",
                        "ClassB",
                        "ClassC"
                    ]
                },
                "NoDisplayIfReadOnly": false
            },
            "Publish": false,
            "DisableCrossSearch": false,
            "LockedTime": "1899-12-30T00:00:00",
            "LockedUser": 0,
            "ApiCountDate": "1899-12-30T00:00:00",
            "ApiCount": 0,
            "Comments": "[]",
            "Creator": 1,
            "Updator": 1,
            "CreatedTime": "2023-08-17T09:00:00",
            "ApiVersion": 1.1,
            "ClassHash": {
            },
            "NumHash": {
            },
            "DateHash": {
            },
            "DescriptionHash": {
            },
            "CheckHash": {
            },
            "AttachmentsHash": {
            }
        }
    }
}

Note

バージョン1.5.10.0以降では、SiteSettingsの「AI連携」の設定に含まれるAPIキーは、マスクした文字列********です。サイト作成APIやサイトパッケージのインポートでこの値を使ってサイトを作成すると、作成したサイトのAPIキーは空になります。作成後に「テーブルの管理:AI連携」でAPIキーを設定し直してください。

サンプルコード

Note

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

1. 複数のテーブルの、項目の物理名と表示名の対応表をCSVに出力する

サイトID一覧(CSV)のテーブルごとに、サイト取得APIでエディタの項目を取得し、物理名(ClassAなど)と表示名(「顧客名」など)の対応表を、1行1項目のCSVに出力します。表示名が設定されていない項目は、既定の表示名(「分類B」など)で補います。

実務での使いどころ

スクリプト・API・拡張SQLを書くときや、テーブルの設計書をまとめるときに、項目の物理名と表示名の対応を一覧で確かめたいときに使えます。対応は、テーブルごとに「テーブルの管理」の「エディタ」を開いて1項目ずつ確かめる必要があり、複数のテーブルをまとめて一覧にする機能はありません。

事前準備

1:対応表を作りたいテーブルのIDを、1行目を見出しSiteIdにしたCSV(sites.csv、UTF-8)に書きます。

2:サンプルコードのBASE_URL・API_KEYを書き換えてください。APIキーのユーザには、各テーブルの「サイトの管理権限」が必要です。バージョン1.5.10.0以降は、サイトの管理権限が無いとサイトの設定(SiteSettings)を取得できないためです。

Python
# ==========================================================
# 項目の対応表:サイトID一覧(CSV)のテーブルごとに、サイト取得APIでエディタの項目を取得し、
# 「物理名(ClassA など)と表示名(顧客名 など)」の対応表を1行1項目のCSVに出力します。
# Columns に表示名が無い項目は、既定の表示名で補います。
# APIキーのユーザーには、各テーブルの「サイトの管理権限」が必要です(1.5.10.0 以降、無いと
# SiteSettings を取得できません)。
# ==========================================================
import csv
import re
from pathlib import Path

import requests

# ===== 設定 =====
BASE_URL = "【URL】"
API_KEY = "【APIキー】"
INPUT_CSV = Path("./sites.csv")               # 1行目は見出し「SiteId」
OUTPUT_CSV = Path("./column_labels.csv")

# 表示名を変えていない項目の、既定の表示名
BASE_LABELS = {
    "IssueId": "ID", "ResultId": "ID", "Title": "タイトル", "Body": "内容", "StartTime": "開始",
    "CompletionTime": "完了", "WorkValue": "作業量", "ProgressRate": "進捗率", "RemainingWorkValue": "残作業量",
    "Status": "状況", "Manager": "管理者", "Owner": "担当者", "Locked": "ロック", "Comments": "コメント",
}
# 拡張項目(ClassA・NumB など)は「種類+A〜Z」が既定の表示名(分類A・数値B など)
EXTENDED_LABELS = {"Class": "分類", "Num": "数値", "Date": "日付", "Description": "説明", "Check": "チェック", "Attachments": "添付ファイル"}
HEADER = ["サイトID", "テーブル名", "タブ", "物理名", "表示名", "表示名を変えたか", "備考"]


def get_site(site_id):
    """サイト取得APIでサイトを取得する。取得できなければ None とメッセージを返す"""
    response = requests.post(
        f"{BASE_URL}/api/items/{site_id}/getsite",
        json={"ApiVersion": 1.1, "ApiKey": API_KEY},
        headers={"Content-Type": "application/json"},
        timeout=60,
    )
    body = response.json()
    if response.status_code != 200:
        return None, body.get("Message", f"HTTP {response.status_code}")
    return body["Response"]["Data"], ""


def default_label(column_name):
    if column_name in BASE_LABELS:
        return BASE_LABELS[column_name]
    m = re.fullmatch(r"(Class|Num|Date|Description|Check|Attachments)([A-Z])", column_name)
    return f"{EXTENDED_LABELS[m.group(1)]}{m.group(2)}" if m else column_name


def site_rows(site_id):
    site, message = get_site(site_id)
    if site is None:
        return [[site_id, "", "", "", "", "", message]]
    title = site.get("Title", "")
    if site.get("ReferenceType") not in ("Issues", "Results"):
        return [[site_id, title, "", "", "", "", "テーブルではないため対象外"]]
    settings = site.get("SiteSettings")
    if not settings:
        return [[site_id, title, "", "", "", "", "設定を取得できない(サイトの管理権限が無い)"]]
    editor = settings.get("EditorColumnHash")
    if not editor:
        return [[site_id, title, "", "", "", "", "エディタの項目が既定のまま(表示名も既定)"]]
    # Columns に表示名が無い項目は、既定の表示名で補う
    labels = {c["ColumnName"]: c["LabelText"] for c in settings.get("Columns", []) if c.get("LabelText")}
    rows = []
    for tab, names in editor.items():
        # 見出し(_Section-1)やリンク(_Links-…)など、項目ではない要素は飛ばす
        for name in [n for n in names if not n.startswith("_")]:
            changed = name in labels and labels[name] != default_label(name)
            rows.append([site_id, title, tab, name, labels.get(name, default_label(name)), "はい" if changed else "", ""])
    return rows


def read_site_ids(path):
    with open(path, encoding="utf-8-sig", newline="") as f:
        return list(dict.fromkeys(row["SiteId"].strip() for row in csv.DictReader(f) if row["SiteId"].strip()))


def main():
    rows = [row for site_id in read_site_ids(INPUT_CSV) for row in site_rows(site_id)]
    with open(OUTPUT_CSV, "w", encoding="utf-8-sig", newline="") as f:
        writer = csv.writer(f)
        writer.writerow(HEADER)
        writer.writerows(rows)
    print(f"{OUTPUT_CSV} に {len(rows)} 行を出力しました。")


if __name__ == "__main__":
    main()

出力の例(column_labels.csv)

サイトID,テーブル名,タブ,物理名,表示名,表示名を変えたか,備考
887,顧客台帳,General,ResultId,ID,,
887,顧客台帳,General,Title,タイトル,,
887,顧客台帳,General,ClassA,顧客名,はい,
887,顧客台帳,General,ClassB,分類B,,
869,案件フォルダ,,,,,テーブルではないため対象外

注記

  • 対象は、エディタに出している項目です。エディタの項目を一度も変えていないテーブルは、備考に「既定のまま」と出します。
  • 見出しやリンクなど、項目ではない要素は出しません。
  • サイトの管理権限が無いテーブルは、備考に「設定を取得できない(サイトの管理権限が無い)」と出します。
  • 拡張項目は、A〜Zの項目(分類A〜分類Zなど)の既定の表示名で補います。

対応バージョン

対応バージョン 内容
1.3.4.0 以降 機能追加
1.5.10.0 以降 サイトの管理権限が無いユーザが実行した場合、SiteSettingsを取得できないよう変更
AI連携のAPIキー(ApiKey)を、マスクした文字列で返却するよう変更