作为系统管理员,您可以使用云 API 以编程方式完成常见基础架构管理任务,例如为角色或用户分配权限、创建或更新作业或查看作业返回数据。可以在具有 Salt 主节点的环境中安装 sseapiclient,也可以在没有 Salt 主节点的环境中安装。

开始前

使用 sseapiclient 之前,请完成以下必备条件:

  1. 如果要在具有 Salt 主节点的环境中使用 sseapiclient
    1. 如果未在 Salt 主节点上安装主节点插件,请参见安装并配置主节点插件,了解安装说明。sseapiclient 与主节点插件捆绑在一起,会在安装该插件时进行安装。
    2. 确认在 Salt 主节点上安装了版本 8.11.1 或更高版本的主节点插件。可以在主节点插件工作区中找到主节点插件版本。

      还可以通过主节点插件工作区更新 Salt 主节点上的主节点插件。有关详细信息,请参见使用“主节点插件”工作区

  2. 如果要在没有 Salt 主节点的环境中使用 sseapiclient
    1. 运行以下命令,在设备上安装 Pika Python 和 PyJWT 库:
      pip3 install pika==1.3.1
      pip3 install pyjwt==2.4.0
    2. 主节点插件工作区下载 sseapiclient 的最新版本。然后运行以下命令,在设备上安装 sseapiclient
      pip3 install SSEApiClient-file-name.whl

      有关详细信息,请参见使用“主节点插件”工作区

    3. 确认 sseapiclient 版本与 Automation Config 的版本相匹配。可以在主节点插件工作区中找到 Automation Config 版本。
  3. Automation Config 中创建作业。有关详细信息,请参见如何创建作业

生成 API 令牌

在连接到云 API 之前,必须使用 Cloud Services 控制台生成 API 令牌。此令牌用于通过 VMware Cloud Services 对 Salt 主节点进行身份验证。

  1. 在 Cloud Services 控制台工具栏中,单击您的用户名,然后选择我的帐户 > API 令牌
  2. 单击生成令牌

    CSP 中的 API 令牌页面

  3. 填写表单。

    在 CSP 中生成令牌表单

    1. 输入令牌的名称。
    2. 选择令牌的生存时间 (TTL)。默认持续时间为六个月。
      注: 如果遭到入侵,不会过期的令牌可能会带来安全风险。如果发生这种情况,必须撤销令牌。
    3. 定义令牌的范围。
      范围 说明
      服务角色

      服务角色是内置的预定义权限集,可授予 VMware Cloud Services 的访问权限。

      要访问 Automation Config 服务,请搜索 Automation Config 服务,然后选择所需的服务角色。有关可用服务角色列表,请参见如何定义用户角色

    4. (可选)设置电子邮件首选项,以便在令牌即将过期时接收提醒。
    5. 单击生成

      新生成的 API 令牌将显示在生成的令牌窗口中。

  4. 将令牌凭据保存到安全位置。

    生成令牌后,您将只能在 API 令牌页面上看到令牌的名称,而看不到凭据。要重新生成令牌,请单击重新生成

  5. 单击继续

进行 API 调用

生成 API 令牌后,可以使用 sseapiclientcURL 进行 API 调用。

要进行 API 调用,请执行以下操作:

  1. 登录到安装了 sseapiclient 的环境。
  2. 运行以下命令,并将服务器值替换为特定于您区域的 Automation Config URL,将 API 令牌值替换为之前生成的 API 令牌。以下代码示例展示了 US 区域的 API 调用。
    Python
    from sseapiclient import APIClient
    client = APIClient(server='https://ssc-gateway.mgmt.cloud.vmware.com', csp_api_token='<api-token>')
    
    client.api.job.get_jobs()
    Python
    #For non-prod environments (e.g. scaleperf). Note the extra argument to the constructor:
    from sseapiclient import APIClient
    client = APIClient(server='https://ssc-gateway.scaleperf.symphony-dev.com', csp_api_token='<api-token>', csp_url='https://console-stg.cloud.vmware.com/')
    
    client.api.job.get_jobs()
    cURL
    SERVER="https://ssc-gateway.mgmt.cloud.vmware.com" && \
    API_TOKEN="<api-token>" && \
    BEARER_TOKEN=$(curl --silent 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode "api_token=$API_TOKEN" \
    | grep -o '"access_token":"[^"]*' | grep -o '[^"]*$') && \
    XSRFTOKEN=$(curl -s -I -X POST "$SERVER/account/login/" \
    --header "Authorization: Bearer $BEARER_TOKEN" \
    | awk '/X-XSRFTOKEN:|x-xsrftoken:/ {gsub("\r","",$2);print $2}') && \
    curl --location --request POST "$SERVER/rpc" \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $BEARER_TOKEN" \
    --header "X-XSRFTOKEN: $XSRFTOKEN" \
    --header "Cookie: _xsrf=$XSRFTOKEN; _xsrf=$XSRFTOKEN" \
    --data '{
        "resource": "job",
        "method": "get_jobs",
        "kwarg": {},
        "args": []
    }'
    表 1. Automation Config 的区域 URL
    区域 Automation Config URL
    US https://ssc-gateway.mgmt.cloud.vmware.com
    德国 https://de.ssc-gateway.mgmt.cloud.vmware.com
    印度 https://in.ssc-gateway.mgmt.cloud.vmware.com
    加拿大 https://ca.ssc-gateway.mgmt.cloud.vmware.com
    澳大利亚 https://au.ssc-gateway.mgmt.cloud.vmware.com
    UK https://uk.ssc-gateway.mgmt.cloud.vmware.com

结果

jobs.get_jobs() 端点返回包含所有作业的列表。以下代码示例展示了一个成功响应示例。
Python
RPCResponse(riq=3, ret={'count': 1, 'results': [{'uuid': '60c14cfc-09ca-4b5a-bc76-8294287c2e6c',
 'name': 'Check disk usage', 'desc': 'Checks disk usage on targeted devices', 'cmd': 'local',
 'tgt_uuid': '7f93b928-388b-11e6-b133-346895ecb8f3', 'fun': 'disk.usage', 'arg': {'arg': [], 'kwarg':
 {}}, 'masters': [], 'metadata': {'auth': {'owner': {'uuid': '8964e9f3-6864-4fe5-ba4a-ab4530caa8ca',
 'config_name': 'internal', 'username': 'root'}, 'access': {}}}, 'tgt_name': 'CentOS'}], 'limit': 50},
 error=None, warnings=[])
cURL
{'riq': 3, 'ret': {'count': 1, 'results': [{'uuid': '60c14cfc-09ca-4b5a-bc76-8294287c2e6c',
 'name': 'Check disk usage', 'desc': 'Checks disk usage on targeted devices', 'cmd': 'local',
 'tgt_uuid': '7f93b928-388b-11e6-b133-346895ecb8f3', 'fun': 'disk.usage', 'arg': {'arg': [], 'kwarg':
 {}}, 'masters': [], 'metadata': {'auth': {'owner': {'uuid': '8964e9f3-6864-4fe5-ba4a-ab4530caa8ca',
 'config_name': 'internal', 'username': 'root'}, 'access': {}}}, 'tgt_name': 'CentOS'}], 'limit': 50}, 'error': null, 'warnings': []}
注: 某些函数需要管理特权,例如 client.api.admin.trim_database()。如果您没有足够的权限,API 将引发错误。

要使用管理功能,可以生成新的 API 令牌并选择超级用户服务角色。

后续操作

阅读 VMware Developer 门户上的 API (RaaS) 文档,了解有关可用资源的更多信息。