ZStack HTTP API使用

56308 ワード
server IaaS 私有雲
1.紹介
ZStackのAPI原語はJSON形式のメッセージで、各種のメッセージバスで呼び出すことができ、現在ZStackが使用しているデフォルトのメッセージバスはRabbitMQである.この特性のためにZStackのAPIを様々なフォーマットにカプセル化することができる.ZStackは皆さんの使用を便利にするために、HTTPサーバを持っています.ユーザーはHTTP POSTを通じてAPI JSONテキストを送信することができます.このHTTPサーバは自動的にAPIメッセージに変換して呼び出しを実現します.
今後ZStack APIをRestful形式にカプセル化しますが、現在のHTTP POSTがAPI JSON原語を送信する方法はずっと保持されています.
ZStackのコマンドラインツール(zstack-cli)は、HTTP POSTメソッドを完全に使用してAPIを呼び出すものであり、ユーザが読みやすいように、すべてのAPIに対するユーザマニュアルの解釈はzstack-cliを例に挙げており、各cliコマンドはAPIに対応している.ユーザーは、中国語のユーザーマニュアルで各APIの詳細な説明を得ることができます.
zstack-cliのlogによって、ユーザーはすべてのAPI呼び出しと返される特定のフォーマット(すなわちHTTP POSTのBODY)を表示することができる.
Logパス:/var/log/zstack/zstack-cli
ユーザーはtail-f/var/log/zstack/zstack-cliを使用してlogをリアルタイムで表示することをお勧めします.これにより、zstack-cliでAPIを実行するときに、特定の呼び出しと出力をリアルタイムで観測できます.例:

   
   
   
   
    
    
    
    
    
  1.  >>LogInByAccount accountName=admin password=password
    2. 
   
   
   
   
  
        ，    LOG         ： 
  

   
   
   
   
    
    
    
    
    
  1. 2016-02-16 16:29:48,664 DEBUG [apibinding.api] async call[url: http://localhost:8080/zstack/api/, request: {"org.zstack.header.identity.APILogInByAccountMsg": {"password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86", "session": {}, "accountName": "admin"}}]
    2. 
    
    
    
    
  2.  2016-02-16 16:29:48,741 DEBUG [apibinding.api] async call[url: http://localhost:8080/zstack/api/, response: {"org.zstack.header.identity.APILogInReply":{"inventory":{"uuid":"083f3518d1bd469fa0ff789fc1a25382","accountUuid":"36c27e8ff05c4780bf6d2fa65700f22e","userUuid":"36c27e8ff05c4780bf6d2fa65700f22e","expiredDate":"Feb 17, 2016 12:29:48 PM","createDate":"Feb 16, 2016 4:29:48 PM"},"success":true}}]
    3. 
   
   
   
   
  
ここhttp://localhost:8080/zstack/api/HTTP び しのURLであり、request の  はAPI び し のHTTP POSTのBODYであり、 えばここでLogInByAccountというAPIのHTTP POST BODYは、

   
   
   
   
    
    
    
    
    
  1.  {
    2. 
    
    
    
    
  2.  "org.zstack.header.identity.APILogInByAccountMsg": {
    3. 
    
    
    
    
  3.  "password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86",
    4. 
    
    
    
    
  4.  "session": {},
    5. 
    
    
    
    
  5.  "accountName": "admin"
    6. 
    
    
    
    
  6.  }
    7. 
    
    
    
    
  7.  }
    8. 
   
   
   
   
  
response     API   HTTP response BODY，    LogInByAccount    ： 
  

   
   
   
   
    
    
    
    
    
  1. {
    2. 
    
    
    
    
  2.  "org.zstack.header.identity.APILogInReply": {
    3. 
    
    
    
    
  3.  "inventory": {
    4. 
    
    
    
    
  4.  "uuid": "083f3518d1bd469fa0ff789fc1a25382",
    5. 
    
    
    
    
  5.  "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
    6. 
    
    
    
    
  6.  "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
    7. 
    
    
    
    
  7.  "expiredDate": "Feb 17, 2016 12:29:48 PM",
    8. 
    
    
    
    
  8.  "createDate": "Feb 16, 2016 4:29:48 PM"
    9. 
    
    
    
    
  9.  },
    10. 
    
    
    
    
  10.  "success": true
    11. 
    
    
    
    
  11.  }
    12. 
    
    
    
    
  12.  }
    13. 
   
   
   
   
  
2.APIのフォーマット
ZStack APIの び しと りはいずれもJSON  で  され、フォーマットは1つのentryのJSON mapのみであり、このentryのkeyはAPI   であり、valueは   な  を  する1つのmapである.API   は、API び しまたは  を  に すために  され、ユーザはそれをAPIの  と なすことができる.  の では、API び しの   はorg.zstack.header.identity.APILogInByAccountMsgであり、APIが す   はorg.zstack.header.identity.APILogInReplyである.
3.HTTPリターンコード
リターンコード
  
200 
HTTP び しに  しました.しかし、APIの  に  したわけではなく、APIの    はAPIが すsuccessフィールドによって  され、trueは  を す.falseは  を す
その 
  は  のHTTPリターンコードと じであり、 えば500はInternal Server Errorを す.404はNo such pageを す
4. HTTP Response Body 
APIのHTTP responseは、クエリAPIが  したかどうかを び し がポーリングする  があるJob  を す.API Jobのフォーマットは  の りである.
フィールド
を  します.
  
uuid 
   
JOB UUIDは、ユーザがAPI JOBの  の    を い わせることができる.state==Doneの  、このフィールドはNULLになります.
state 
   
JOB  .2つの  を む:Processing、このJOBはまだ  されている;Done、JOBは  しました
result 
   
API  、JSON   .state=Processingの  、このフィールドはNULLです.
createdDate 
   
JOB    
finishedDate 
   
JOB    
state==ProcessingのJob :

   
   
   
   
    
    
    
    
    
  1.  {
    2. 
    
    
    
    
  2.  "uuid": "fee83ed8529340cd8528b3b408dc16b0",
    3. 
    
    
    
    
  3.  "state": "Processing",
    4. 
    
    
    
    
  4.  "createdDate": "Feb 16, 2016 5:01:11 PM"
    5. 
    
    
    
    
  5.  }
    6. 
   
   
   
   
  
state==DoneのJob :

   
   
   
   
    
    
    
    
    
  1.  {
    2. 
    
    
    
    
  2.  "uuid": "fee83ed8529340cd8528b3b408dc16b0",
    3. 
    
    
    
    
  3.  "state": "Done",
    4. 
    
    
    
    
  4.  "createdDate": "Feb 16, 2016 5:01:11 PM",
    5. 
    
    
    
    
  5.  "finishedDate": "Feb 16, 2016 5:01:12 PM",
    6. 
    
    
    
    
  6.  "result": "{"org.zstack.header.zone.APICreateZoneEvent":{"inventory":{"uuid":"f1ed8f95163c4b6c88a8c0673b7913b7","name":"xx","state":"Enabled","type":"zstack","createDate":"Feb 16, 2016 5:01:12 PM","lastOpDate":"Feb 16, 2016 5:01:12 PM"},"success":true}}"
    7. 
    
    
    
    
  7.  }
    8. 
   
   
   
   
  
4.1 API JOBの  を い わせる
APIが び されると、HTTP responseは、ユーザがuuidを してJobの  を  する  があるJob  を す.
       http://locahost:8080/api/result/{job uuid}    HTTP Get  ，  ： 


   
   
   
   
    
    
    
    
    
  1. curl http://localhost:8080/zstack/api/result/fee83ed8529340cd8528b3b408dc16b0
    2. 
   
   
   
   
  
そのHTTP responseはJob  を し,ユーザはJobのstateフィールドを  することによってJobが  したか かを  し,Jobの  をポーリングし ける  があるか かを  することができる.
5.APIの び しフロー
ZStack APIの び しの   な れは:
  •  LogInByAccountを び し、  のAPI び しのtoken 
    • としてSession UUIDを  する
  •  API 1 
    • を び す
  •  API 2 
    • を び す
  •  ... ... 
    •   
  •  API N 
    • を び す
  •  LogOut 
    • を び す
    5.1ログイン
     のAPIを び す に、ユーザは、  のAPI び しのtokenとして、セッションUUIDを  するために、まずLogInByAccountを び す  がある.このAPIの   は、org.zstack.header.identity.APILogInByAccountMsgであり、  のフィールドを む.
    フィールド
      
    accountName 
    ユーザー . えばadmin|
    password 
    パスワード.zstackはパスワードを    せず,  にデータベースに  されているパスワードデータと     する.CreateAccountのようなAPIを び す  、パスワードはsha 512で   することをお めします.
    デフォルトのユーザー パスワード:ZStackのデフォルトのユーザー はadminで、そのパスワードの  はpasswordで、sha 512ハッシュの の  は
    b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86  
       API JSON     ： 

    
   
   
   
   
      
    
    
    
    
    1.  {
      2. 
    
    
    
    
    2.  "org.zstack.header.identity.APILogInByAccountMsg": {
      3. 
    
    
    
    
    3.  "password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86",
      4. 
    
    
    
    
    4.  "accountName": "admin"
      5. 
    
    
    
    
    5.  }
      6. 
    
    
    
    
    6.  }
      7. 
   
   
   
   
      
    このAPIはcurlで び されます.
    
   
   
   
   
      
    
    
    
    
    1.  curl -H "Content-Type: application/json" -d '{"org.zstack.header.identity.APILogInByAccountMsg": {"password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86", "accountName": "admin"}}' http://localhost:8080/zstack/api
      2. 
   
   
   
   
      
     されるJob  は のとおりです.
    
  
  
  
  
      
   
   
   
   
    1. {
      2. 
   
   
   
   
    2.  "state": "Done",
      3. 
   
   
   
   
    3.  "createdDate": "Feb 16, 2016 7:15:01 PM",
      4. 
   
   
   
   
    4.  "finishedDate": "Feb 16, 2016 7:15:01 PM",
      5. 
   
   
   
   
    5.  "result": "{"org.zstack.header.identity.APILogInReply":{"inventory":{"uuid":"9eba9754f8c2470cbb377088e61c4da2","accountUuid":"36c27e8ff05c4780bf6d2fa65700f22e","userUuid":"36c27e8ff05c4780bf6d2fa65700f22e","expiredDate":"Feb 17, 2016 3:15:01 PM","createDate":"Feb 16, 2016 7:15:01 PM"},"success":true}}"
      6. 
   
   
   
   
    6.  }
      7. 
  
  
  
  
      
     result      API   ，JSON   ：
      
    
  
  
  
  
      
   
   
   
   
    1.  {
      2. 
   
   
   
   
    2.  "org.zstack.header.identity.APILogInReply": {
      3. 
   
   
   
   
    3.  "inventory": {
      4. 
   
   
   
   
    4.  "uuid": "9eba9754f8c2470cbb377088e61c4da2",
      5. 
   
   
   
   
    5.  "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
      6. 
   
   
   
   
    6.  "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
      7. 
   
   
   
   
    7.  "expiredDate": "Feb 17, 2016 3:15:01 PM",
      8. 
   
   
   
   
    8.  "createDate": "Feb 16, 2016 7:15:01 PM"
      9. 
   
   
   
   
    9.  },
      10. 
   
   
   
   
    10.  "success": true
      11. 
   
   
   
   
    11.  }
      12. 
   
   
   
   
    12.  }
      13. 
  
  
  
  
      
    ここでuuidフィールドは、 たちが  とするSession UUIDです.
    5.2  API び し
      (LogInByAccount)、  (LogOut)などの  のAPIを き、 りは  のAPIであり、 び し にLogInが  したSession UUIDに  する  があり、そのJSON  は  の りである.
    
   
   
   
   
      
    
    
    
    
    1.  {
      2. 
    
    
    
    
    2.  "API   ": {
      3. 
    
    
    
    
    3.  "session": {
      4. 
    
    
    
    
    4.  "uuid": "LogIn    session UUID"
      5. 
    
    
    
    
    5.  }，
      6. 
    
    
    
    
    6.  "API   1"： ...，
      7. 
    
    
    
    
    7.  "API   2”： ...
      8. 
    
    
    
    
    8.  }
      9. 
    
    
    
    
    9.  }
      10. 
   
   
   
   
        :zstack-cliで  する APIの   、request、responseは、/var/log/zstack/zstack-cliを  することによって ることができます.
    5.3  
      なAPIを  したら、LogOut APIを び して  のセッションを  する  があります.このAPIの   はorg.zstack.header.identity.APILogOutMsgであり、そのJSON  は:
    

    
   
   
   
   
      
    
    
    
    
    1.  {
      2. 
    
    
    
    
    2.  "org.zstack.header.identity.APILogOutMsg": {
      3. 
    
    
    
    
    3.  "sessionUuid": "  LogOut Session UUID"
      4. 
    
    
    
    
    4.  }
      5. 
    
    
    
    
    5.  }
      6. 
   
   
   
   
      
     curl  ： 

    
   
   
   
   
      
    
    
    
    
    1.  curl -H "Content-Type: application/json" -d '{"org.zstack.header.identity.APILogOutMsg": {"sessionUuid": "083f3518d1bd469fa0ff789fc1a25382"}}' http://localhost:8080/zstack/api
      2. 
   
   
   
   
      
    6.ZoneのCurlの を  する
    ここではZoneの  という を いて,ZStackのAPIをCurlで  で び す  を す.
    6.1ログイン
     び し:
    
   
   
   
   
      
    
    
    
    
    1. curl -H "Content-Type: application/json" -d '{"org.zstack.header.identity.APILogInByAccountMsg": {"password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86", "accountName": "admin"}}' http://localhost:8080/zstack/api
      2. 
   
   
   
   
      
     り :
    
   
   
   
   
      
    
    
    
    
    1. {"state":"Done","createdDate":"Feb 16, 2016 7:53:14 PM","finishedDate":"Feb 16, 2016 7:53:14 PM","result":"{"org.zstack.header.identity.APILogInReply":{"inventory":{"uuid":"2f68cf0a5783400694bd8efdd536a2a8","accountUuid":"36c27e8ff05c4780bf6d2fa65700f22e","userUuid":"36c27e8ff05c4780bf6d2fa65700f22e","expiredDate":"Feb 17, 2016 3:53:14 PM","createDate":"Feb 16, 2016 7:53:14 PM"},"success":true}}"}
      2. 
   
   
   
   
      
    6.2 Zoneを  
      : 

    
   
   
   
   
      
    
    
    
    
    1. curl -H "Content-Type: application/json" -d '{"org.zstack.header.zone.APICreateZoneMsg": {"session": {"uuid": "2f68cf0a5783400694bd8efdd536a2a8"}, "name": "zone1"}}' http://localhost:8080/zstack/api
      2. 
   
   
   
   
    は、
    
   
   
   
   
      
    
    
    
    
    1. {"uuid":"2252332b14fb42599558577cb24fa168","state":"Processing","createdDate":"Feb 16, 2016 7:55:34 PM"}
      2. 
   
   
   
   
      
    ここではJob UUIDを  しました 2252332 b 14 fb 42599558577 cb 24 fa 168は、ZoneというAPIを  した  をポーリングすることができます.
    ポーリング  :
    
   
   
   
   
      
    
    
    
    
    1. curl http://localhost:8080/zstack/api/result/2252332b14fb42599558577cb24fa168
      2. 
   
   
   
   
      
     り :
    
   
   
   
   
      
    
    
    
    
    1. {"uuid":"2252332b14fb42599558577cb24fa168","state":"Done","createdDate":"Feb 16, 2016 7:55:34 PM","finishedDate":"Feb 16, 2016 7:55:34 PM","result":"{"org.zstack.header.zone.APICreateZoneEvent":{"inventory":{"uuid":"dd625f8fb2074f4fa1c0870ef76bb24a","name":"zone1","state":"Enabled","type":"zstack","createDate":"Feb 16, 2016 7:55:34 PM","lastOpDate":"Feb 16, 2016 7:55:34 PM"},"success":true}}"}
      2. 
   
   
   
   
      
    ここではAPIが  しているのを て、state==Done.APIの  は、resultフィールドにJSON   として  されます.successフィールドがtrueであるため、API び しが  したことがわかります.
    6.3  
     び し:
    
   
   
   
   
      
    
    
    
    
    1. curl -H "Content-Type: application/json" -d '{"org.zstack.header.identity.APILogOutMsg": {"sessionUuid": "2252332b14fb42599558577cb24fa168"}}' http://localhost:8080/zstack/api
      2. 
   
   
   
   
      
     り :
    
   
   
   
   
      
    
    
    
    
    1. {"state":"Done","createdDate":"Feb 16, 2016 8:04:36 PM","finishedDate":"Feb 16, 2016 8:04:37 PM","result":"{"org.zstack.header.identity.APILogOutReply":{"success":true}}"}
      2. 
   
   
   
   
      
    7.ZoneのPythonの を  する
    ここをクリックして  なコードを ることができます.
    
   
   
   
   
      
    
    
    
    
    1. import httplib
      2. 
    
    
    
    
    2. import json
      3. 
    
    
    
    
    3. import time
      4. 
    
    
    
    
    4.  
      5. 
    
    
    
    
    5. # return a dict containing API return value
      6. 
    
    
    
    
    6. def api_call(session_uuid, api_id, api_content):
      7. 
    
    
    
    
    7.  conn = httplib.HTTPConnection("localhost", 8080)
      8. 
    
    
    
    
    8.  headers = {"Content-Type": "application/json"}
      9. 
    
    
    
    
    9.  
      10. 
    
    
    
    
    10.  if session_uuid:
      11. 
    
    
    
    
    11.  api_content["session"] = {"uuid": session_uuid}
      12. 
    
    
    
    
    12.  
      13. 
    
    
    
    
    13.  api_body = {api_id: api_content}
      14. 
    
    
    
    
    14.  
      15. 
    
    
    
    
    15.  conn.request("POST", "/zstack/api", json.dumps(api_body))
      16. 
    
    
    
    
    16.  response = conn.getresponse()
      17. 
    
    
    
    
    17.  
      18. 
    
    
    
    
    18.  if response.status != 200:
      19. 
    
    
    
    
    19.  raise Exception("failed to make an API call, %s, %s" % (response.status, response.reason))
      20. 
    
    
    
    
    20.  
      21. 
    
    
    
    
    21.  rsp_body = response.read()
      22. 
    
    
    
    
    22.  
      23. 
    
    
    
    
    23.  rsp = json.loads(rsp_body)
      24. 
    
    
    
    
    24.  
      25. 
    
    
    
    
    25.  if rsp["state"] == "Done":
      26. 
    
    
    
    
    26.  return json.loads(rsp["result"])
      27. 
    
    
    
    
    27.  
      28. 
    
    
    
    
    28.  job_uuid = rsp["uuid"]
      29. 
    
    
    
    
    29.  def query_until_done():
      30. 
    
    
    
    
    30.  conn.request("GET", "/zstack/api/result/%s" % job_uuid)
      31. 
    
    
    
    
    31.  response = conn.getresponse()
      32. 
    
    
    
    
    32.  if response.status != 200:
      33. 
    
    
    
    
    33.  raise Exception("failed to query API result, %s, %s" % (response.status, response.reason))
      34. 
    
    
    
    
    34.  
      35. 
    
    
    
    
    35.  rsp_body = response.read()
      36. 
    
    
    
    
    36.  rsp = json.loads(rsp_body)
      37. 
    
    
    
    
    37.  if rsp["state"] == "Done":
      38. 
    
    
    
    
    38.  return json.loads(rsp["result"])
      39. 
    
    
    
    
    39.  
      40. 
    
    
    
    
    40.  time.sleep(1)
      41. 
    
    
    
    
    41.  print "Job[uuid:%s] is still in processing" % job_uuid
      42. 
    
    
    
    
    42.  return query_until_done()
      43. 
    
    
    
    
    43.  
      44. 
    
    
    
    
    44.  return query_until_done()
      45. 
    
    
    
    
    45.  
      46. 
    
    
    
    
    46.  
      47. 
    
    
    
    
    47.  
      48. 
    
    
    
    
    48. def error_if_fail(rsp):
      49. 
    
    
    
    
    49.  success = rsp.values()[0]["success"]
      50. 
    
    
    
    
    50.  if not success: 
      51. 
    
    
    
    
    51.  error = rsp.values()[0]["error"]
      52. 
    
    
    
    
    52.  raise Exception("failed to login, %s" % json.dumps(error))
      53. 
    
    
    
    
    53.  
      54. 
    
    
    
    
    54. def login():
      55. 
    
    
    
    
    55.  content = {
      56. 
    
    
    
    
    56.  "accountName": "admin",
      57. 
    
    
    
    
    57.  "password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86"
      58. 
    
    
    
    
    58.  }
      59. 
    
    
    
    
    59.  rsp = api_call(None, "org.zstack.header.identity.APILogInByAccountMsg", content)
      60. 
    
    
    
    
    60.  error_if_fail(rsp)
      61. 
    
    
    
    
    61.  
      62. 
    
    
    
    
    62.  session_uuid = rsp.values()[0]["inventory"]["uuid"]
      63. 
    
    
    
    
    63.  
      64. 
    
    
    
    
    64.  print "successfully login, session uuid is: %s" % session_uuid
      65. 
    
    
    
    
    65.  return session_uuid
      66. 
    
    
    
    
    66.  
      67. 
    
    
    
    
    67.  
      68. 
    
    
    
    
    68. def create_zone(session_uuid):
      69. 
    
    
    
    
    69.  content = {"name": "zone1"}
      70. 
    
    
    
    
    70.  
      71. 
    
    
    
    
    71.  rsp = api_call(session_uuid, "org.zstack.header.zone.APICreateZoneMsg", content)
      72. 
    
    
    
    
    72.  error_if_fail(rsp)
      73. 
    
    
    
    
    73.  
      74. 
    
    
    
    
    74.  print "successfully created zone1"
      75. 
    
    
    
    
    75.  
      76. 
    
    
    
    
    76.  
      77. 
    
    
    
    
    77. def logout(session_uuid):
      78. 
    
    
    
    
    78.  content = {"sessionUuid": session_uuid}
      79. 
    
    
    
    
    79.  rsp = api_call(None, "org.zstack.header.identity.APILogOutMsg", content)
      80. 
    
    
    
    
    80.  error_if_fail(rsp)
      81. 
    
    
    
    
    81.  
      82. 
    
    
    
    
    82.  print "successfully logout"
      83. 
    
    
    
    
    83. session_uuid = login()
      84. 
    
    
    
    
    84. create_zone(session_uuid)
      85. 
    
    
    
    
    85. logout(session_uuid)
      86.
    C++20 latch
    @Resource導入サービスが空の問題を解決する方法