From ce8b8fb393af3ddfeed6bf745bf4bf87efa670fe Mon Sep 17 00:00:00 2001 From: Muscle Date: Tue, 23 Apr 2024 12:15:31 +0900 Subject: [PATCH] add REST API command line interface 'rest-cli'. --- Dockerfile | 3 +- README.md | 77 ++++++++++++++++ docusaurus/docs/known-issues/known-issues.md | 6 ++ scripts/helper_functions.sh | 3 +- scripts/rest_api.sh | 92 ++++++++++++++++++++ 5 files changed, 179 insertions(+), 2 deletions(-) create mode 100644 scripts/rest_api.sh diff --git a/Dockerfile b/Dockerfile index 8cd778f12..b41346409 100644 --- a/Dockerfile +++ b/Dockerfile @@ -155,7 +155,8 @@ COPY ./scripts /home/steam/server/ RUN chmod +x /home/steam/server/*.sh && \ mv /home/steam/server/backup.sh /usr/local/bin/backup && \ mv /home/steam/server/update.sh /usr/local/bin/update && \ - mv /home/steam/server/restore.sh /usr/local/bin/restore + mv /home/steam/server/restore.sh /usr/local/bin/restore && \ + ln -sf /home/steam/server/rest_api.sh /usr/local/bin/rest-cli WORKDIR /home/steam/server diff --git a/README.md b/README.md index bba41f259..3a6bf7058 100644 --- a/README.md +++ b/README.md @@ -333,6 +333,83 @@ This will open a CLI that uses RCON to write commands to the Palworld Server. For a full list of commands go to: [https://tech.palworldgame.com/settings-and-operation/commands](https://tech.palworldgame.com/settings-and-operation/commands) +## Using REST API + +REST API is not enabled by default. +If used, please set REST_API_ENABLED to true. + +docker-compose.override.yml + +```yaml +services: + palworld: + environment: + REST_API_ENABLED: true +``` + +The palworld-server-docker image provides rcon-cli as well as rest-cli. + +```bash +$ docker exec -it palworld-server rest-cli +Usage: rest-cli [options] +api: + announce ... announce message. + ban ... ban player. + info ... show server informations. + kick ... kick player. + metrics ... show server metrics. + players ... show online players. + save ... save the world. + settings ... show server settings. + shutdown ... shutdown server. + stop ... force stop server. + unban ... unban player. +options: + '{...}' ... json. + - ... json from stdin. + -h, --help ... help. +``` + +For example, you can broadcast a message to everyone in the server with the following command: + +CLI parameter style: + +```bash +docker exec -i palworld-server rest-cli announce "Broadcast Hello everyone" +``` + +JSON parameter style: + +```bash +docker exec -i palworld-server rest-cli announce '{"message":"Broadcast Hello everyone"}' +``` + +JSON pipe style: + +```bash +echo '{"message":"Broadcast Hello everyone"}' | docker exec -i palworld-server rest-cli announce - +``` + +rest-cli allows you to call REST APIs directly without exposing ports outside the container. + +### List of REST APIs + +| API | Info | +|----------------------------------|-----------------------------------------------------| +| info | Get the server information. | +| players | Get player list. | +| settings | Get the server settings. | +| metrics | Get the server metrics. | +| announce | Announce message. | +| kick {SteamID} | Kick player. | +| ban {SteamID} | Ban player. | +| unban {SteamID} | Unban player. | +| save | Save the world. | +| shutdown {Seconds} {MessageText} | Shutdown the server | +| stop | Force stop the server. | + +For an official documents go to: [https://tech.palworldgame.com/category/rest-api](https://tech.palworldgame.com/category/rest-api) + ## Creating a backup To create a backup of the game's save at the current point in time, use the command: diff --git a/docusaurus/docs/known-issues/known-issues.md b/docusaurus/docs/known-issues/known-issues.md index f5316cb0f..47d846299 100644 --- a/docusaurus/docs/known-issues/known-issues.md +++ b/docusaurus/docs/known-issues/known-issues.md @@ -35,6 +35,12 @@ As an example, if I use: only Hello is transmitted. +:::note info +Using REST API solves it. + +`docker exec -it palworld-server rest-cli announce "Hello world"` +::: + ## XBox GamePass players unable to join At the moment, Xbox Gamepass/Xbox Console players will not be able to join a dedicated server. diff --git a/scripts/helper_functions.sh b/scripts/helper_functions.sh index 4a2c3c4cd..0019c31a2 100644 --- a/scripts/helper_functions.sh +++ b/scripts/helper_functions.sh @@ -176,7 +176,8 @@ REST_API(){ local URL="http://localhost:${REST_API_PORT}/v1/api/${1}" local ACCEPT="Accept: application/json" local USERPASS="admin:${ADMIN_PASSWORD}" - if [ "${DATA}" = "" ]; then + local post_api="save|stop" + if [ "${DATA}" = "" ] && [[ ! ${1} =~ ${post_api} ]]; then curl -s -L -X GET "${URL}" -H "${ACCEPT}" -u "${USERPASS}" else curl -s -L -X POST "${URL}" -H "${ACCEPT}" -u "${USERPASS}" --json "${DATA}" diff --git a/scripts/rest_api.sh b/scripts/rest_api.sh new file mode 100644 index 000000000..455fa2d55 --- /dev/null +++ b/scripts/rest_api.sh @@ -0,0 +1,92 @@ +#!/bin/bash +SCRIPT=$(basename "${0}") +ORGPATH=$(readlink -fn "${0}") +ORGDIR=$(dirname "${ORGPATH}") +#shellcheck source=scripts/helper_functions.sh +source "${ORGDIR}/helper_functions.sh" +help="-h|--help" +if [ $# -lt 1 ] || [[ ${1} =~ ${help} ]]; then +cat << EOF +Usage: ${SCRIPT} [options] +api: + announce ... announce message. + ban ... ban player. + info ... show server informations. + kick ... kick player. + metrics ... show server metrics. + players ... show online players. + save ... save the world. + settings ... show server settings. + shutdown ... shutdown server. + stop ... force stop server. + unban ... unban player. +options: + '{...}' ... json. + - ... json from stdin. + -h, --help ... help. +EOF + exit 1 +fi + +if [ ! "${REST_API_ENABLED,,}" = true ]; then + echo "ERROR: REST_API_ENABLED=False" + exit 1 +fi + +api="${1}" +json="${2}" +api_required_json="announce|ban|kick|shutdown|unban" +if [[ ${api} =~ ${api_required_json} ]]; then + if [ $# -lt 2 ]; then + echo "input json required." + exit 1 + fi + if [ "${json}" = "-" ]; then + json="$(cat -)" + elif [[ ! ${json} =~ ^\{ ]]; then + usage="Usage: ${SCRIPT} ${api}" + case ${api} in + "announce") + if [[ ${json} =~ ${help} ]]; then + echo "${usage} " + exit 1 + fi + json="{\"message\":\"${2}\"}" + ;; + "ban") + if [[ ${json} =~ ${help} ]]; then + echo "${usage} [message]" + exit 1 + fi + msg=${3:-You are banned.} + json="{\"userid\":\"${2}\",\"message\":\"${msg}\"}" + ;; + "kick") + if [[ ${json} =~ ${help} ]]; then + echo "${usage} [message]" + exit 1 + fi + msg=${3:-You are kicked.} + json="{\"userid\":\"${2}\",\"message\":\"${msg}\"}" + ;; + "shutdown") + if [[ ${json} =~ ${help} ]]; then + echo "${usage} [message]" + exit 1 + fi + sec=${2} + msg=${3:-Server will shutdown in ${sec} sec.} + json="{\"waittime\":${sec},\"message\":\"${msg}\"}" + ;; + "unban") + if [[ ${json} =~ ${help} ]]; then + echo "${usage} " + exit 1 + fi + json="{\"userid\":\"${2}\"}" + ;; + esac + fi +fi + +REST_API "${api}" "${json}" && echo ""