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

  {}