From 417f01e9950afaa0ee861359fdc097875f613273 Mon Sep 17 00:00:00 2001 From: Mark Mandel Date: Mon, 18 May 2020 16:18:06 -0700 Subject: [PATCH] Player Tracking: REST SDK Reference Reference for player tracking API for the REST interface for the SDK. Also regrouped as how we now have it in the Client SDK guide. Work on #1033 --- .../en/docs/Guides/Client SDKs/rest.md | 199 ++++++++++++++---- 1 file changed, 161 insertions(+), 38 deletions(-) diff --git a/site/content/en/docs/Guides/Client SDKs/rest.md b/site/content/en/docs/Guides/Client SDKs/rest.md index 2f3d8f105b..002efc6006 100644 --- a/site/content/en/docs/Guides/Client SDKs/rest.md +++ b/site/content/en/docs/Guides/Client SDKs/rest.md @@ -38,7 +38,9 @@ You can read more about OpenAPI/Swagger code generation in their [Command Line T ## Reference -### Ready +### Lifecycle Management + +#### Ready Call when the GameServer is ready to accept connections @@ -46,62 +48,74 @@ Call when the GameServer is ready to accept connections - Method: `POST` - Body: `{}` -#### Example +##### Example ```bash $ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/ready ``` -### Health +#### Health Send a Empty every d Duration to declare that this GameServer is healthy - Path: `/health` - Method: `POST` - Body: `{}` -#### Example +##### Example ```bash $ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/health ``` -### Shutdown +#### Reserve -Call when the GameServer session is over and it's time to shut down +Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation. -- Path: `/shutdown` +- Path: `/reserve` - Method: `POST` -- Body: `{}` +- Body: `{"seconds": "5"}` -#### Example +##### Example ```bash -$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown +$ curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve ``` -### Set Label +#### Allocate -Apply a Label with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata. +With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`. +For those scenarios, this SDK functionality exists. -See the SDK [SetLabel]({{< ref "/docs/Guides/Client SDKs/_index.md#setlabel-key-value" >}}) documentation for restrictions. +{{< alert title="Note" color="info">}} +Using a [GameServerAllocation]({{< ref "/docs/Reference/gameserverallocation.md" >}}) is preferred in all other scenarios, +as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you +relinquish control to an external service which likely doesn't have as much information as Agones. +{{< /alert >}} -#### Example +##### Example ```bash -$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label +$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate ``` -### Set Annotation +#### Shutdown + +Call when the GameServer session is over and it's time to shut down -Apply a Annotation with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata +- Path: `/shutdown` +- Method: `POST` +- Body: `{}` -#### Example +##### Example ```bash -$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation +$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown ``` -### GameServer +### Configuration Retrieval + + +#### GameServer Call when you want to retrieve the backing `GameServer` configuration details @@ -142,7 +156,7 @@ Response: } ``` -### Watch GameServer +#### Watch GameServer Call this when you want to get updates of when the backing `GameServer` configuration is updated. @@ -160,34 +174,143 @@ Response: {"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}} {"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}} ``` +### Metadata Management -### Reserve +#### Set Label -Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation. +Apply a Label with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata. -- Path: `/reserve` -- Method: `POST` -- Body: `{"seconds": "5"}` +See the SDK [SetLabel]({{< ref "/docs/Guides/Client SDKs/_index.md#setlabel-key-value" >}}) documentation for restrictions. -#### Example +##### Example ```bash -$ curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve +$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label ``` -### Allocate +#### Set Annotation -With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`. -For those scenarios, this SDK functionality exists. +Apply an Annotation with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata -{{< alert title="Note" color="info">}} -Using a [GameServerAllocation]({{< ref "/docs/Reference/gameserverallocation.md" >}}) is preferred in all other scenarios, -as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you -relinquish control to an external service which likely doesn't have as much information as Agones. -{{< /alert >}} +##### Example + +```bash +$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation +``` + +{{% feature publishVersion="1.6.0" %}} +### Player Tracking + +{{< alpha title="Player Tracking" gate="PlayerTracking" >}} -#### Example +#### Alpha: PlayerConnect + +This function increases the SDK’s stored player count by one, and appends this playerID to +`GameServer.Status.Players.IDs`. + +##### Example ```bash -$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate +$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connect ``` + +Response: +```json +{"bool":true} +``` + +#### Alpha: PlayerDisconnect + +This function decreases the SDK’s stored player count by one, and removes the playerID from +[`GameServer.Status.Players.IDs`][playerstatus]. + +##### Example + +```bash +$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/disconnect +``` + +Response: +```json +{"bool":true} +``` + +#### Alpha: SetPlayerCapacity + +Update the [`GameServer.Status.Players.Capacity`][playerstatus] value with a new capacity. + +##### Example + +```bash +$ curl -d '{"count": 5}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity +``` + +#### Alpha: GetPlayerCapacity + +This function retrieves the current player capacity. This is always accurate from what has been set through this SDK, +even if the value has yet to be updated on the GameServer status resource. + +##### Example + +```bash +$ curl -d '{}' -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity +``` + +Response: +```json +{"count":"5"} +``` + +#### Alpha: GetPlayerCount + +This function returns if the playerID is currently connected to the GameServer. +This is always accurate from what has been set through this SDK, +even if the value has yet to be updated on the GameServer status resource. + +```bash +$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/count +``` + +Response: +```json +{"count":"2"} +``` + +##### Example + +#### Alpha: IsPlayerConnected + +This function returns if the playerID is currently connected to the GameServer. This is always accurate from what has +been set through this SDK, +even if the value has yet to be updated on the GameServer status resource. + +##### Example + +```bash +$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected/uzh7i +``` + +Response: +```json +{"bool":true} +``` + +#### Alpha: GetConnectedPlayers + +This function returns the list of the currently connected player ids. This is always accurate from what has been set +through this SDK, even if the value has yet to be updated on the GameServer status resource. + +##### Example + +```bash +$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected +``` + +Response: +```json +{"list":["uzh7i","3zh7i"]} +``` + +[playerstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#PlayerStatus" >}} + +{{% /feature %}} \ No newline at end of file