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

# 搭配混合任務使用 API
<a name="braket-jobs-api"></a>

您可以使用 直接存取 Amazon Braket 混合任務並與之互動API。不過，API直接使用 時，無法使用預設值和便利方法。

**注意**  
我們強烈建議您使用 Amazon Braket [Python SDK 與 Amazon Braket ](https://github.com/aws/amazon-braket-sdk-python)混合任務互動。它提供方便的預設值和保護，協助您的混合式任務成功執行。

本主題涵蓋使用 的基本概念API。如果您選擇使用 API，請記住，此方法可能更為複雜，並準備好進行多次反覆運算，讓您的混合式任務得以執行。

若要使用 API，您的帳戶應該具有具有 `AmazonBraketFullAccess`受管政策的角色。

**注意**  
如需如何使用 `AmazonBraketFullAccess`受管政策取得角色的詳細資訊，請參閱[啟用 Amazon Braket ](braket-enable-overview.md) 頁面。

此外，您需要 **執行角色**。此角色將傳遞給 服務。您可以使用 **Amazon Braket 主控台**建立角色。使用**許可和設定**頁面上的**執行角色**索引標籤，為混合任務建立預設角色。

`CreateJob` API 需要您指定混合任務的所有必要參數。若要使用 Python，請將演算法指令碼檔案壓縮為 tar 套件，例如 input.tar.gz 檔案，然後執行下列指令碼。更新角括號 (`<>`) 中的程式碼部分，以符合您的帳戶資訊和指定混合任務啟動路徑、檔案和方法的進入點。

```
from braket.aws import AwsDevice, AwsSession
import boto3
from datetime import datetime

s3_client = boto3.client("s3")
client = boto3.client("braket")

project_name = "job-test"
job_name = project_name + "-" + datetime.strftime(datetime.now(), "%Y%m%d%H%M%S")
bucket = "amazon-braket-<your_bucket>"
s3_prefix = job_name

job_script = "input.tar.gz"
job_object = f"{s3_prefix}/script/{job_script}"
s3_client.upload_file(job_script, bucket, job_object)

input_data = "inputdata.csv"
input_object = f"{s3_prefix}/input/{input_data}"
s3_client.upload_file(input_data, bucket, input_object)

job = client.create_job(
    jobName=job_name,
    roleArn="arn:aws:iam::<your_account>:role/service-role/AmazonBraketJobsExecutionRole",  # https://docs.aws.amazon.com/braket/latest/developerguide/braket-manage-access.html#about-amazonbraketjobsexecution
    algorithmSpecification={
        "scriptModeConfig": {
            "entryPoint": "<your_execution_module>:<your_execution_method>",
            "containerImage": {"uri": "292282985366.dkr.ecr.us-west-1.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py37-ubuntu18.04"},   # Change to the specific region you are using
            "s3Uri": f"s3://{bucket}/{job_object}",
            "compressionType": "GZIP"
        }
    },
    inputDataConfig=[
        {
            "channelName": "hellothere",
            "compressionType": "NONE",
            "dataSource": {
                "s3DataSource": {
                    "s3Uri": f"s3://{bucket}/{s3_prefix}/input",
                    "s3DataType": "S3_PREFIX"
                }
            }
        }
    ],
    outputDataConfig={
        "s3Path": f"s3://{bucket}/{s3_prefix}/output"
    },
    instanceConfig={
        "instanceType": "ml.m5.large",
        "instanceCount": 1,
        "volumeSizeInGb": 1
    },
    checkpointConfig={
        "s3Uri":  f"s3://{bucket}/{s3_prefix}/checkpoints",
        "localPath": "/opt/omega/checkpoints"
    },
    deviceConfig={
        "priorityAccess": {
            "devices": [
                "arn:aws:braket:us-west-1::device/qpu/rigetti/Ankaa-3"
            ]
        }
    },
    hyperParameters={
        "hyperparameter key you wish to pass": "<hyperparameter value you wish to pass>",
    },
    stoppingCondition={
        "maxRuntimeInSeconds": 1200,
        "maximumTaskLimit": 10
    },
)
```

建立混合任務後，您可以透過 `GetJob`API或 主控台存取混合任務詳細資訊。若要從執行`createJob`程式碼的 Python 工作階段取得混合式任務詳細資訊，如先前範例所示，請使用下列 Python 命令。

```
getJob = client.get_job(jobArn=job["jobArn"])
```

若要取消混合任務，`CancelJob`API請使用任務Amazon Resource Name的 () 呼叫 'JobArn'。

```
cancelJob = client.cancel_job(jobArn=job["jobArn"])
```

您可以使用 `checkpointConfig` 參數`createJob`API將檢查點指定為 的一部分。

```
    checkpointConfig = {
        "localPath" : "/opt/omega/checkpoints",
        "s3Uri": f"s3://{bucket}/{s3_prefix}/checkpoints"
    },
```

**注意**  
localPath `checkpointConfig`不能以下列任一預留路徑開頭：`/opt/ml`、`/tmp`、 `/opt/braket`或 `/usr/local/nvidia`。