WebAPI（サーバースクリプト）

サーバーサイドのスクリプトは、GSP（Groovy Server Pages） または .groovy エンドポイントとして実行されます。スクリプトには WebAPI をはじめとする多数のグローバルが渡され、HTTP とコンテンツ（JCR）を扱えます。

実行モデル

スクリプトは JCR コンテンツとして保存され、次の URL で実行されます。

/bin/cms.cgi/<workspace>/content/<path>/<script.groovy|.gsp>

例: GET /bin/cms.cgi/web/content/commerce/endpoints/health.groovy?days=7

スクリプトのグローバル（主なもの）

名前	型	用途
`out`	`Writer`	レスポンス本文への出力
`request` / `response`	`HttpServletRequest` / `HttpServletResponse`	HTTP の入出力
`session` / `application`	`HttpSession` / `ServletContext`	セッション・アプリ共有
`repositorySession`	`Session`（script resource API）	JCR コンテンツの読み書きの主役
`resource`	`Resource`	処理中の JCR リソース
`WebAPI`	`WebAPI`	include / fetch / パラメーター / エンコード（`request` がある場合のみ）
`log`（`LoggerAPI`）	`LoggerAPI`	ログ出力（debug/info/warn/error）
`JSON` / `YAML`	—	JSON / YAML の解析・直列化
`XPath` / `MetadataAPI`	—	クエリ・メタデータ
`ProcessAPI` / `IntegrationAPI`	—	BPM / EIP 連携
`EventAdminAPI` / `cluster` / `CryptoAPI` / `MimeTypeAPI` / `SessionAPI`	—	イベント・クラスター・暗号・MIME・セッション生成

（request / response / out は HTTP 経由で実行されたときのみ利用可能です）

WebAPI のメソッド

メソッド	用途
`include(path)`	別リソース（GSP 等）を取り込む（`/` 始まりはワークスペース基準）
`forward(path)`	別リソースへフォワード
`importContent(path[, encoding])`	ファイル / HTTP の内容を出力（`jcr://`・相対/絶対パス・HTTP URL）
`getParameter(name)`	リクエストパラメーター（単一値またはアップロードファイル）
`fetch(uri)`	HTTP GET（接続 3 秒・要求 10 秒のタイムアウト）。`WebResource` を返す
`encodeURIComponent` / `encodeURI` / `decodeURIComponent`	URI エンコード/デコード

Session（script resource API）

repositorySession から、コンテンツを操作します。

getResource(absPath) / getResourceByIdentifier(id) / getRootFolder() — リソース取得
commit() / rollback() — 保存 / 破棄
deploy() — etc/jcr/deploy と etc/jcr/provisioning を反映
adaptTo(javax.jcr.Session) — 低レベル JCR セッションへ適応
impersonate(userId) / newSession() — 別ユーザー / 新規セッション
isAdmin() / isAnonymous() / isService() / getUserID() — 実行主体の判定

Resource の主な操作

読み取り: getContent() / getContentAsStream() / getProperty(name) / list()
書き込み: write(content) / setProperty(name, value) / createFile() / createFolder() / getOrCreateFile(name)
移動など: moveTo(path) / copyTo(path) / remove()
バージョン: addVersionControl() / checkout() / checkin() / checkpoint()
ロック: lock() / unlock() / isLocked()
ACL: getAccessControlList() / setAccessControlList(acl) / canRead() / canWrite()

例

GSP のインクルード:

<% WebAPI.include("/content/public/inc/head_start.gsp") %>

JSON エンドポイント（.groovy）:

int days = (request.getParameter("days") ?: "7") as int
try {
  def snapshot = Health.snapshot(repositorySession, days)
  response.setStatus(200)
  response.setHeader("Content-Type", "application/json")
  response.getWriter().write(new ObjectMapper().writeValueAsString(snapshot))
} catch (Exception e) {
  log.error("health endpoint error: ${e.message}", e)
  response.setStatus(500)
}

コンテンツの作成と保存:

def res = repositorySession.getRootFolder().getOrCreateFile("content/notes/hello.json")
res.write('{"hello":"world"}')
res.setProperty("jcr:mimeType", "application/json")
repositorySession.commit()

認可・サービスアカウントの考え方は「ユーザー・ロール・権限」を参照してください。

フォルダ記述子 `.web.yml`（公開とレンダリング設定）

フォルダに .web.yml を置くと、そのフォルダ（と配下）の公開時の挙動を宣言できます。設定ファイルなので Web には配信されません。設定は最も近い祖先フォルダの .web.yml まで遡って解決されます。

サイトのドキュメントルート（`site.root`）

site:
  root: true                      # このフォルダを公開サイトのルート（URL の `/`）とする
  baseURL: "https://example.com"  # 公開時の正規オリジン（任意のメタデータ）

root: true を宣言したフォルダがドキュメントルートになります。たとえば /content/public に置けば、公開サイトはこのフォルダを / としてマウントします（NGINX で /index.gsp → /content/public/index.gsp のように向ける構成）。

これにより、コンテンツ内のサイトルート絶対パス（例 href="/docs/css/docs.css"、src="/img/logo.svg"）が、配信されるマウント位置に応じて正しく解決されます。著者は常に絶対パスで書くだけで、次のいずれの経路でも同じ見た目になります。

配信経路	`/docs/css/docs.css` の解決先
公開サイト	オリジン直下（`https://example.com/docs/css/docs.css`）
webtop テキストエディターのプレビュー	`/bin/cms.cgi/<workspace>/content/public/docs/css/docs.css`

プレビューは Service Worker でこの書き換えを行うため、**HTTPS（セキュアコンテキスト）**で動作します。HTTP の場合や、.web.yml でルートを宣言していないフォルダのファイルでは絶対パスの書き換えは行われません（相対パスは従来どおり解決）。baseURL は正規オリジンを表す任意のメタデータで、パスベースのプレビュー書き換えには使用しません。

テンプレートへのバインディング（`render`）

ソースファイル（例: *.md）を、ファイルごとに設定せずフォルダ単位でテンプレートに束ねて描画できます。

render:
  - match: "*.md"                                  # グロブ（* ? に対応）でファイル名を一致
    template: "/content/WEB-INF/templates/doc.html"
    output: ["html"]                               # 許可する出力拡張子（省略時は任意）

ファイル個別に web.template プロパティを設定した場合はそちらが優先されます。バインディング結果と解決済みドキュメントルートは、GraphQL の node.webRender（templated / fromDescriptor / source / outputs / documentRoot）として参照できます。