本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Session Manager API 入門
<a name="getting-started"></a>

Amazon DCV Session Manager API 提供用於管理遠端桌面工作階段的自動化界面。透過此 API，開發人員可以透過程式設計方式建立、列出、啟動、停止和以其他方式控制 DCV 工作階段。這允許將 Amazon DCV 功能整合到自訂應用程式和工作流程。透過利用此 API，組織可以簡化遠端視覺化工作負載的管理，並將許多常見任務自動化。

在開始呼叫 Amazon DCV API 之前，您將需要取得存取字符來驗證您的應用程式，並授權它存取必要的資源。Amazon DCV API 使用 OAuth 2.0 進行身分驗證，因此您需要註冊應用程式並擷取必要的登入資料。取得存取權杖後，您就可以開始將請求傳送至 Amazon DCV API 端點，以開始處理資料。

**Topics**
+ [步驟 1：產生您的 API 用戶端](client-sdk.md)
+ [步驟 2：註冊您的用戶端 API](credentials.md)
+ [步驟 3：取得存取字符並提出 API 請求](request.md)

# 步驟 1：產生您的 API 用戶端
<a name="client-sdk"></a>

Session Manager APIs 是在單一 YAML 檔案中定義。APIs 是以 OpenAPI3.0 規格為基礎，定義 RESTful APIs 的標準、語言無關界面。如需詳細資訊，請參閱 [OpenAPI 規格](https://swagger.io/specification/)。

您可以使用 YAML 檔案，以其中一種支援的語言產生 API 用戶端。若要這樣做，您必須使用 Swagger Codegen 3.0 或更新版本。如需支援語言的詳細資訊，請參閱 [swagger-codegen 儲存庫](https://github.com/swagger-api/swagger-codegen#overview)。

**產生 API 用戶端**

1. 從 Session Manager Broker 下載 Session Manager API YAML 檔案。YAML 檔案可在下列 URL 取得。

   ```
   https://broker_host_ip:port/dcv-session-manager-api.yaml
   ```

1. 安裝 Swagger Codegen。
   + macOS

     ```
     $ brew install swagger-codegen
     ```
   + 其他平台

     ```
     $ git clone https://github.com/swagger-api/swagger-codegen --branch 3.0.0
     ```

     ```
     $ cd swagger-codegen
     ```

1. 產生 API 用戶端。
   + macOS

     ```
     $ swagger-codegen generate -i /path_to/yaml_file -l language -o $output_folder
     ```
   + 其他平台

     ```
     $ mvn clean package
     ```

     ```
     $ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i /path_to/yaml_file -l language -o output_folder
     ```

# 步驟 2：註冊您的用戶端 API
<a name="credentials"></a>

API 請求使用存取字符來驗證您的登入資料。這些登入資料是根據用戶端向中介裝置註冊時產生的用戶端 ID 和用戶端密碼。

若要存取此字符，您需要向中介裝置註冊。使用 [register-api-client](https://docs.aws.amazon.com/dcv/latest/sm-admin/register-api-client.html) 註冊用戶端 API。

如果您沒有用戶端的用戶端 ID 和用戶端密碼，您必須向您的中介裝置管理員請求這些 ID 和用戶端密碼。

# 步驟 3：取得存取字符並提出 API 請求
<a name="request"></a>

此範例會逐步解說設定存取字符的步驟，然後示範如何提出基本 API 請求。這將為您提供基礎知識，以開始建置採用 Amazon DCV API 技術的更進階應用程式。

在此範例中，我們將示範如何使用 `DescribeSessions` API 來執行此操作。

**Example**  
首先，匯入應用程式所需的模型。  
然後，我們會宣告用戶端 ID (`__CLIENT_ID`)、用戶端密碼 (`__CLIENT_SECRET`) 和中介裝置 URL 的變數，包括連接埠號碼 (`__PROTOCOL_HOST_PORT`)。  
接著，我們會建立名為 的函數`build_client_credentials`，以產生用戶端登入資料。若要產生用戶端登入資料，您必須先串連用戶端 ID 和用戶端密碼，並將值與冒號 (`client_ID:client_password`) 分隔，然後 Base64 編碼整個字串。  

```
import swagger_client
import base64
import requests
import json
from swagger_client.models.describe_sessions_request_data import DescribeSessionsRequestData
from swagger_client.models.key_value_pair import KeyValuePair
from swagger_client.models.delete_session_request_data import DeleteSessionRequestData
from swagger_client.models.update_session_permissions_request_data import UpdateSessionPermissionsRequestData
from swagger_client.models.create_session_request_data import CreateSessionRequestData

__CLIENT_ID = '794b2dbb-bd82-4707-a2f7-f3d9899cb386'
__CLIENT_SECRET = 'MzcxNzJhN2UtYjEzNS00MjNjLTg2N2YtMjFlZmRlZWNjMDU1'
__PROTOCOL_HOST_PORT = 'https://<broker-hostname>:8443'

def build_client_credentials():
    client_credentials = '{client_id}:{client_secret}'.format(client_id=__CLIENT_ID, client_secret=__CLIENT_SECRET)
    return base64.b64encode(client_credentials.encode('utf-8')).decode('utf-8')
```
現在我們有用戶端登入資料，我們可以用它向中介裝置請求存取字符。為此，我們建立一個名為 的函數`get_access_token`。您必須在 `POST`上呼叫 ` https://Broker_IP:8443/oauth2/token?grant_type=client_credentials`，並提供授權標頭，其中包含基本編碼的用戶端登入資料，以及 的內容類型`application/x-www-form-urlencoded`。  

```
def get_access_token():
    client_credentials = build_client_credentials()
    headers = {
        'Authorization': 'Basic {}'.format(client_credentials),
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    endpoint = __PROTOCOL_HOST_PORT + '/oauth2/token?grant_type=client_credentials'
    print('Calling', endpoint, 'using headers', headers)
    res = requests.post(endpoint, headers=headers, verify=True)
    if res.status_code != 200:
        print('Cannot get access token:', res.text)
        return None
    access_token = json.loads(res.text)['access_token']
    print('Access token is', access_token)
    return access_token
```
現在，我們建立執行個體化用戶端 API 所需的函數。若要執行個體化用戶端 API，您必須指定用戶端組態和要用於請求的標頭。`get_client_configuration` 函數會建立組態物件，其中包含中介裝置的 IP 地址和連接埠，以及中介裝置的自我簽署憑證路徑，您應該已從中介裝置管理員收到該憑證。`set_request_headers` 函數會建立包含用戶端登入資料和存取字符的請求標頭物件。  

```
def get_client_configuration():
    configuration = swagger_client.Configuration()
    configuration.host = __PROTOCOL_HOST_PORT
    configuration.verify_ssl = True
    # configuration.ssl_ca_cert = cert_file.pem
    return configuration

def set_request_headers(api_client):
    access_token = get_access_token()
    api_client.set_default_header(header_name='Authorization',
                                  header_value='Bearer {}'.format(access_token))

def get_sessions_api():
    api_instance = swagger_client.SessionsApi(swagger_client.ApiClient(get_client_configuration()))
    set_request_headers(api_instance.api_client)
    return api_instance
```
最後，我們會建立呼叫 `DescribeSessions` API 的主要方法。如需詳細資訊，請參閱[DescribeSessions](DescribeSessions.md)。  

```
def describe_sessions(session_ids=None, next_token=None, tags=None, owner=None):
    filters = list()
    if tags:
        for tag in tags:
            filter_key_value_pair = KeyValuePair(key='tag:' + tag['Key'], value=tag['Value'])
            filters.append(filter_key_value_pair)
    if owner:
        filter_key_value_pair = KeyValuePair(key='owner', value=owner)
        filters.append(filter_key_value_pair)

    request = DescribeSessionsRequestData(session_ids=session_ids, filters=filters, next_token=next_token)
    print('Describe Sessions Request:', request)
    api_instance = get_sessions_api()
    api_response = api_instance.describe_sessions(body=request)
    print('Describe Sessions Response', api_response)
    
def main():
    describe_sessions(
        session_ids=['SessionId1895', 'SessionId1897'],
        owner='an owner 1890',
        tags=[{'Key': 'ram', 'Value': '4gb'}])
```