From a72ad1f1d13e5bd3bb13b434fcc561395babacba Mon Sep 17 00:00:00 2001 From: dev4unet Date: Thu, 13 Jun 2024 14:25:57 +0900 Subject: [PATCH] Added detailed REST subcommand user documentation --- docs/cb-mayfly-rest.md | 143 ++++++++++++++++++++++++++++++++--------- 1 file changed, 114 insertions(+), 29 deletions(-) diff --git a/docs/cb-mayfly-rest.md b/docs/cb-mayfly-rest.md index d483ce6..afcf114 100644 --- a/docs/cb-mayfly-rest.md +++ b/docs/cb-mayfly-rest.md @@ -1,47 +1,132 @@ -## Cloud-Migrator CLI REST API 호출 도구 (mayfly-rest) -Cloud-Migrator CLI API 호출 도구(mayfly)는 Cloud-Migrator 시스템의 RESTful API를 호출하는 간단한 명령 줄 인터페이스입니다. 이 도구를 사용하여 서비스와 액션을 호출하고 API 요청을 실행할 수 있습니다. -# 설치 -mayfly CLI 도구를 설치하려면 다음 단계를 따르십시오: +## RESTful 명령 사용 가이드 -1. GitHub 저장소에서 소스 코드를 다운로드하거나 클론합니다. -2. Go 언어로 빌드하거나 실행 가능한 파일을 다운로드합니다. -3. 실행 가능한 파일을 시스템 경로에 추가하여 mayfly를 전역으로 사용할 수 있도록 합니다. +이 가이드에서는 `cm-mayfly`의 `rest` 서브 커맨드를 이용하여 `RESTful` 기반으로 Cloud-Migrator 시스템의 Open API를 실행하는 방법에 대해 소개합니다. -## cm-mayfly 소스코드 다운로드 +`rest` 서브 커맨드는 Cloud-Migrator 시스템의 간단한 REST API 호출을 위해 가볍게 제공되는 유틸성 기능입니다. + + +## 순서 +1. 실행파일 다운로드 +1. rest 명령어 사용법 + + + +## 실행파일 다운로드 +실행 파일을 이용하거나 git 소스를 내려 받아서 실행 가능합니다. +아래 방법으로 실행 파일을 다운로드하거나 README를 참고하여 최신 소스 코드를 빌드하세요. ```bash -git clone https://github.com/cm-mayfly/cm-mayfly.git +$ wget https://github.com/cloud-barista/cm-mayfly/raw/main/bin/mayfly +$ chmod +x mayfly ``` -# Golang 다운로드 -```bash -wget https://go.dev/dl/go1.21.4.linux-amd64.tar.gz + +## rest 명령어 사용법 + +RESTful의 기본적인 get/post/delete/put/patch 명령을 지원하며 `mafly rest -h` 명령으로 rest 서브 커멘드에서 제공하는 기능들에 대해서 자세히 살펴 볼 수 있습니다. + ``` +rest api call -## cm-mayfly 소스코드 빌드 -```bash -cd cm-mayfly/src -go build -o mayfly main.go +Usage: + mayfly rest [flags] + mayfly rest [command] + +Available Commands: + delete REST API calls with DELETE methods + get REST API calls with GET methods + patch REST API calls with PATCH methods + post REST API calls with POST methods + put REST API calls with PUT methods + +Flags: + --authScheme string sets the auth scheme type in the HTTP request.(Exam. OAuth)(The default auth scheme is Bearer) + --authToken string sets the auth token of the 'Authorization' header for all HTTP requests.(The default auth scheme is 'Bearer') + -d, --data string Data to send to the server + -f, --file string Data to send to the server from file + -I, --head Show response headers only + -H, --header strings Pass custom header(s) to server + -h, --help help for rest + -o, --output string Write to file instead of stdout + -p, --password string Password for basic authentication + -u, --user string Username for basic authentication + -v, --verbose Show more detail information + +Use "mayfly rest [command] --help" for more information about a command. ``` -# 사용법 +Cloud-Migrator 시스템의 프레임워크들은 REST API 사용시 인증이 필요한 프레임워크와 인증이 필요 없는 프레임워크가 존재하는데 인증이 필요한 경우 REST API에 Bearer 인증을 사용하고있습니다. +REST API를 호출할 때 인증이 필요한 경우에는 --user와 --password 플래그를 이용해서 Bearer 인증을 설정할 수 있으며, 다른 인증 방식이 필요한 경우에는 --authScheme 와 --authToken 플래그를 활용하세요. + -mayfly-rest CLI 도구를 사용하여 REST API를 호출하려면 다음과 같이 명령을 사용합니다 +### header 설정 예시 +헤더 설정이 필요한 경우 -H 또는 --header 플래그를 이용해서 원하는 헤더의 설정이 가능합니다. +``` +$ ./mayfly rest --header "Content-Type:application/json" +``` -mayfly-rest [flags] +### get 메소드 예시 +cb-spider의 cloudos rest api 호출 +``` +$ ./mayfly rest get http://localhost:1024/spider/cloudos -# 예시 -mayfly-rest --header "Content-Type: application/json" --data '{"key": "value"}' +[실행결과] +{"cloudos":["AWS","AZURE","GCP","ALIBABA","TENCENT","IBM","OPENSTACK","CLOUDIT","NCP","NCPVPC","NHNCLOUD","KTCLOUD","KTCLOUDVPC","DOCKER","MOCK","CLOUDTWIN"]} +``` -## 구성 +cb-tumblebug의 aws-eu-south-2 리전 조회 rest api 호출 +``` +$ ./mayfly rest get http://localhost:1024/spider/region/aws-eu-south-2 -mayfly-rest CLI 도구는 REST API 호출을 위한 구성을 사용합니다. 이 구성은 사용자 지정 헤더, 인증 정보 등을 포함하고 있습니다. +[실행결과] +{"RegionName":"aws-eu-south-2","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"eu-south-2"},{"Key":"Zone","Value":"eu-south-2a"}],"AvailableZoneList":null} +``` -# 기능 -사용자 지정 헤더 설정: --header 플래그를 사용하여 사용자 지정 헤더를 지정할 수 있습니다. -인증 정보 설정: --authToken 및 --authScheme 플래그를 사용하여 인증 토큰 및 스키마를 설정할 수 있습니다. -데이터 전송: --data 또는 --file 플래그를 사용하여 서버에 데이터를 전송할 수 있습니다. -출력 파일 설정: --output 플래그를 사용하여 응답을 파일로 저장할 수 있습니다. -상세 정보 출력: --verbose 플래그를 사용하여 상세 정보를 표시할 수 있습니다. +### 인증 정보 설정 예시 +-u 또는 --user 플래그와 -p 또는 --password 플래그를 이용해서 호출하는 REST 명령에 Bearer 인증 정보를 설정할 수 있습니다. +``` +$ ./mayfly rest get -u default -p default http://localhost:1323/tumblebug/readyz + +[실행결과] +2024/06/13 13:41:59.924202 WARN RESTY Using Basic Auth in HTTP mode is not secure, use HTTPS +{"message":"CB-Tumblebug is ready"} +``` + +### JSON Data 전달 예시 +-d 또는 --data 플래그를 이용해서 POST 방식 등의 JSON 데이터를 서버에 전달할 수 있습니다. + + +cb-tumblebug에 aws-test-seoul 리전 등록 +``` +$ ./mayfly rest post --header "Content-Type:application/json" http://localhost:1024/spider/region -d '{"RegionName":"aws-test-seoul1","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"ap-northeast-2"},{"Key":"Zone","Value":"ap-northeast-2a"}]}' + +[실행결과] +{"RegionName":"aws-test-seoul1","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"ap-northeast-2"},{"Key":"Zone","Value":"ap-northeast-2a"}],"AvailableZoneList":null} +``` + + +만약, JSON 데이터를 직접 전달하지 않고 전달할 JSON Data가 파일에 저장되어 있다면 -f 또는 --file 옵션으로 전달할 데이터의 파일을 지정할 수도 있습니다. +[seoul.json] +``` +{"RegionName":"aws-test-seoul1","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"ap-northeast-2"},{"Key":"Zone","Value":"ap-northeast-2a"}]}' +``` + +seoul.json 파일을 이용해서 리전 등록 +``` +$ ./mayfly rest post --header "Content-Type:application/json" http://localhost:1024/spider/region --file ./seoul.json + +[실행결과] +{"RegionName":"aws-test-seoul1","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"ap-northeast-2"},{"Key":"Zone","Value":"ap-northeast-2a"}],"AvailableZoneList":null} +``` + +### REST 응답 값을 파일로 저장 +-o 또는 --output 플래그를 이용하면 rest api 호출 결과를 파일로 저장할 수 있습니다. +cb-tumblebug의 aws-eu-south-2 리전 조회 rest api 호출 결과를 result.json으로 저장 +``` +$ ./mayfly rest get http://localhost:1024/spider/region/aws-eu-south-2 --output result.json + +$ cat result.json +{"RegionName":"aws-eu-south-2","ProviderName":"AWS","KeyValueInfoList":[{"Key":"Region","Value":"eu-south-2"},{"Key":"Zone","Value":"eu-south-2a"}],"AvailableZoneList":null} +```