Day8 Swagger UI & Open Match APIs

Swagger UI 是一个将 API 文件与 API 请求产生结合的介面套件，官方已於建立核心的 yaml 中，帮我们部署好 swagger ui service，但今天主要介绍的并非 Swagger UI 本身，而是利用 Swagger UI 来阅读 Open-Match 所提供的 HTTP API 接口。

Install

如果你已按照先前篇幅安装过 Open-Match 核心，那检查一下 swaggerui 有没有存活就好

~ kubectl get pod -n open-match | grep swagger

open-match-swaggerui-6658d4c55b-q5557      1/1     Running   7          18d

port-forward

kubectl port-forward -n open-match svc/open-match-swaggerui 51500:51500

http://127.0.0.1:51500/

如果已经删除核心懒的重装的话，可以直接使用 swagger-ui image，配合官方写好的 swagger config 启动。（可能需注意一下 -v mount 的位置是否为本机专案位置）

docker run -p 51500:8080 -e SWAGGER_JSON=/api/frontend.swagger.json -v ~/open-match/api/:/api swaggerapi/swagger-ui:latest

http://127.0.0.1:51500/

Open Match APIs

Open-Match 配对框架将配对流程拆解为为服务运作，并透过指定接口完成资料的传递，完成过滤与配对的目的。而这些接口分别提供了两种方式使用，HTTP REST & gRPC。基於 gRPC 长连线与可指定 proto 限制输入输出内容，实务上习惯以 gRPC 作为服务间沟通的方式。今天针对几个 API 接口说明其功能，说明时将以 HTTP 进行说明，方便直接使用 curl 测试，其余核心 API 请参考 open-match api。

FrontendService API

• CreateTicket

  • 功能：创建一个配对请求 ticket，并且依据请求的内容赋予 ticket 配对参数，最後这张 ticket 会获得一个唯一 ID，并储存於 open-match-redis 中
  • Method: POST
  • Path: /v1/frontendservice/tickets

  ~ curl -X POST "http://open-match-frontend:51504/v1/frontendservice/tickets" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"ticket\":{}}"
  
  {"id":"c4tf9p9rimb6l7nkng90","create_time":"2021-09-10T06:02:13.073820700Z"}%
  

• DeleteTicket

  • 功能：终止指定的 ticket ID 进行配对，并从 open-match-redis 删除
  • Method: DELETE
  • Path: /v1/frontendservice/tickets/{del_ticket_id}

  ~ curl -X DELETE "http://open-match-frontend:51504/v1/frontendservice/tickets/c4tf9p9rimb6l7nkng90" -H "accept: application/json" -H "Content-Type: application/json"
  
  {}%
  

QueryService API

• QueryTicketIds

  • 功能：依照 pool 的条件取出 list of ticket‘s id ，如果没有在 pool's filter 做限制则全部取出
  • Method: POST
  • Path: /v1/queryservice/ticketids:query

  ~ curl -X POST "http://open-match-query:51503/v1/queryservice/ticketids:query" -H "accept: application/json" -H "Content-Type: application/json" -d '{"pool":{}}'
  
  {"result":{"ids":["c4tg2u9rimb6l7nknga0","c4tg2tprimb6l7nkng9g"]}}
  

• QueryTickets

  • 功能：依照 pool 的条件取出 list of tickets ，如果没有在 pool's filter 做限制则全部取出
  • Method: POST
  • Path: /v1/queryservice/tickets:query

  ~ curl -X POST "http://open-match-query:51503/v1/queryservice/tickets:query" -H "accept: application/json" -H "Content-Type: application/json" -d '{"pool":{}}'
  
  {"result":{"tickets":[{"id":"c4tg2u9rimb6l7nknga0","create_time":"2021-09-10T06:55:53.371609700Z"},{"id":"c4tg2tprimb6l7nkng9g","create_time":"2021-09-10T06:55:51.344243Z"}]}}
  

BackendService API

• FetchMatches

  • 功能：由 Director 向 BackendService 呼叫，并经由 BackendService 呼叫 MMF 取得配对
  • Method: POST
  • Path: /v1/backendservice/matches:fetch

  这边由於不好组参数，改直接改动 demo example Director 呼叫 FetchMatches 的结果印出。也可以同时知道呼叫 FetchMatches 触发的时机是由 Director 发动。

  {
  	"match_id":"profile-a-simple-1v1-matchfunction-time-2021-09-10T08:29:50.16-num-0",
  	"match_profile":"a-simple-1v1-matchfunction",
  	"match_function":"a-simple-1v1-matchfunction",
  	"tickets":[
  		{
  			"id":"c4the51rimb6l7nknph0",
  			"search_fields":{
  				"double_args":{
  				"level":18
  				},
  				"string_args":{
  					"location":"Asia/Japan",
  					"role":"archer"
  				}
  			},
  			"create_time":{
  				"seconds":1631262484,
  				"nanos":550353800
  			}
  		},
  		{
  			"id":"c4the6primb6l7nknpj0",
  				"search_fields":{
  					"double_args":{
  						"level":0
  					},
  				"string_args":{
  					"location":"Asia/Japan",
  					"role":"knight"
  				}
  			},
  			"create_time":{
  				"seconds":1631262491,
  				"nanos":345084200
  			}
  		}
  	]
  }
  

• AssignTickets

  • 功能：将 FetchMatches 取得的配对，重新复写 ticket 内容，并指派到特定的 DGS(游戏服务器)
  • Method: POST
  • Path: /v1/backendservice/tickets:assign

  {}