本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon ECS 服務定義參數 服務定義會定義您的 Amazon ECS 服務的執行方式。下列參數可以在服務定義中指定。 ## 啟動類型 `launchType` 類型：字串 有效值：`EC2` \$1 `FARGATE` \$1 `EXTERNAL` 必要：否 您服務執行所在的啟動類型。如果未指定啟動類型，預設會使用預設的 `capacityProviderStrategy`。 更新服務時，此參數會觸發新的服務部署。 若有指定 `launchType`，則必須省略 `capacityProviderStrategy` 參數。 ## 容量提供者策略 `capacityProviderStrategy` 類型： 物件陣列 必要：否 要用於服務的容量提供者策略。 更新服務時，此參數不會觸發新的服務部署。 容量提供者策略包含一個或多個容量提供者，以及指派給這些容量提供者的 `base` 與 `weight`。容量提供者必須與要在容量提供者策略中使用的叢集相關聯。PutClusterCapacityProviders API 是用於將容量提供者與叢集相關聯。只能使用具有 `ACTIVE` 或 `UPDATING` 狀態的容量提供者。 若有指定 `capacityProviderStrategy`，則必須省略 `launchType` 參數。如果沒有指定 `capacityProviderStrategy` 或 `launchType`，則會使用叢集的 `defaultCapacityProviderStrategy`。 如果您想要指定使用 Auto Scaling 群組的容量提供者，則必須已經建立該容量提供者。可以使用 CreateCapacityProvider API 操作來建立新的容量提供者。 若要使用 AWS Fargate 容量提供者，請指定 `FARGATE`或 `FARGATE_SPOT` 容量提供者。 AWS Fargate 容量提供者適用於所有帳戶，且只需要與要使用的叢集建立關聯。 PutClusterCapacityProviders API 操作是用來在建立叢集之後，更新叢集的可用容量提供者清單。 `capacityProvider` 類型：字串 必要：是 容量提供者的簡短名稱或完整 Amazon Resource Name (ARN)。 `weight` 類型：整數 有效範圍：介於 0 到 1,000 之間的整數。 必要：否 加權值會指定應使用指定容量提供者其已啟動任務總數的相對百分比。 例如，假設您的策略包含兩個容量提供者，且兩者的加權值都是一。當基本條件符合時，工作會平均分配給兩個容量提供者。以此類推，假設您為 *capacityProviderA* 指定了加權值 1；並為 *capacityProviderB* 指定了加權值 4。那麼，每有一個任務使用 *capacityProviderA* 執行，就會有四個任務是使用 *capacityProviderB* 執行。 `base` 類型：整數 有效範圍：介於 0 到 100,000 之間的整數。 必要：否 基礎值指定至少要在指定容量提供者上執行多少任務數量。容量提供者策略中只有一個容量提供者可以定義基礎。 ## 任務定義 `taskDefinition` 類型：字串 必要：否 `family` 和 `revision` (`family:revision`) 或在您服務中執行的任務定義完整 Amazon Resource Name (ARN)。如果 `revision` 未指定，則會使用指定系列的最新 `ACTIVE` 修訂版。 更新服務時，此參數會觸發新的服務部署。 在使用循環更新 (`ECS`) 部署控制器時，必須指定任務定義。 ## 平台作業系統 `platformFamily` 類型：字串 必要：有條件 預設：Linux 在 Fargate 上託管的 Amazon ECS 服務需要此參數。 在 Amazon EC2 上託管的 Amazon ECS 服務會忽略此參數。 執行服務的容器上的作業系統。有效值為 `LINUX`、`WINDOWS_SERVER_2019_FULL`、`WINDOWS_SERVER_2019_CORE`、`WINDOWS_SERVER_2022_FULL` 與 `WINDOWS_SERVER_2022_CORE`。 為服務指定的每個任務的 `platformFamily` 值必須與服務 `platformFamily` 值相符。例如，如果您將 `platformFamily` 設定為 `WINDOWS_SERVER_2019_FULL`，則所有任務的 `platformFamily` 值都必須為 `WINDOWS_SERVER_2019_FULL`。 ## 平台版本 `platformVersion` 類型：字串 必要：否 您服務中任務正在其上執行的平台版本。平台版本僅會為使用 Fargate 啟動類型的任務指定。如果尚未指定，預設會使用最新版本 (`LATEST`)。 更新服務時，此參數會觸發新的服務部署。 AWS Fargate 平台版本用於參考 Fargate 任務基礎設施的特定執行期環境。在您執行任務或建立服務時指定 `LATEST` 平台版本，即可取得任務所能使用的最新平台版本。當您擴展服務規模時，這些任務會收到於服務的目前部署上所指定的平台版本。如需詳細資訊，請參閱[適用於 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。 並未針對使用 EC2 啟動類型的任務指定平台版本。 ## 叢集 `cluster` 類型：字串 必要：否 您服務執行所在之叢集的 Amazon Resource Name (ARN) 簡稱或全稱。若您未指定叢集，即假設您會使用 `default` 叢集。 ## 服務名稱 `serviceName` 類型：字串 必要：是 您的服務名稱。最多允許 255 個字母 （大寫和小寫）、數字、連字號和底線。叢集中不得有相同的服務名稱，但一個區域內或多個區域間的多個叢集中可以有類似的服務名稱。 ## 排程策略 `schedulingStrategy` 類型：字串 有效值：`REPLICA` \$1 `DAEMON` 必要：否 使用的排程策略。如果未指定排程策略，則會使用 `REPLICA` 策略。如需詳細資訊，請參閱[Amazon ECS 服務](ecs_services.md)。 現已推出兩個服務排程器策略概念： + `REPLICA` - 複本排程策略會置放並在整個叢集中維持所需的任務數量。根據預設，服務排程器會將任務分散至各個可用區域。您可以使用任務置放策略和限制條件，來自訂任務置放決策。如需詳細資訊，請參閱[複本排程策略](ecs_service-options.md#service_scheduler_replica)。 + `DAEMON` - 常駐程式排程策略會在每個符合您於叢集中所指定所有任務置放限制條件的作用中容器執行個體上，準確地部署一個任務。使用這項策略時，不需指定所需的任務數量、任務置放策略或使用 Service Auto Scaling 政策。如需詳細資訊，請參閱[常駐程式排程策略](ecs_service-options.md#service_scheduler_daemon)。 **注意** Fargate 任務不支援 `DAEMON` 排程策略。 ## 所需計數 `desiredCount` 類型：整數 必要：否 於指定的任務定義中，要放置在您服務上並保持執行的實例數量。 更新服務時，此參數不會觸發新的服務部署。 如果使用 `REPLICA` 排程策略，則需要此參數。如果該服務使用 `DAEMON` 排程策略，則此參數是選擇性的。 當您使用服務自動擴展時，如果以少於目前執行中任務數量的 `desiredCount` 更新目前執行中的服務，該服務會縮減規模至指定的 `desiredCount`。 ## Deployment configuration (部署組態) `deploymentConfiguration` 類型：物件 必要：否 選用的部署參數，可控制在部署期間執行多少任務以及停止和啟動任務的順序。 更新服務時，此參數不會觸發新的服務部署。 `maximumPercent` 類型：整數 必要：否 如果服務使用滾動更新 (`ECS`) 部署類型，則 `maximumPercent` 參數代表在部署期間，服務中允許處於 `RUNNING`、`STOPPING` 或 `PENDING` 狀態的任務數量上限。以百分比表示 `desiredCount` 即無條件捨去至最接近的整數。您可以使用此參數來定義部署批次大小。例如，如果服務使用 `REPLICA` 服務排程器、`desiredCount` 為 4 項任務，且 `maximumPercent` 值為 200%，則排程器可能會先啟動四項新任務，再停止四項舊任務。前提是有執行此操作所需的叢集資源。使用 `REPLICA` 服務排程器的服務，其預設 `maximumPercent` 值為 200%。 只要用於啟動替代任務的叢集資源可用，Amazon ECS 排程器就會使用此參數，透過先啟動替代任務然後停止運作狀態不良的任務，來取代運作狀態不良的任務。如需有關排程器如何取代運作狀態不良任務的詳細資訊，請參閱 [Amazon ECS 服務](ecs_services.md)。 如果您的服務使用 `DAEMON` 服務排程器類型，`maximumPercent` 應該維持 100%。這是預設值。 部署期間的任務最大數量等於 `desiredCount` 乘以 `maximumPercent`/100，無條件捨去到最接近的整數值。 如果服務使用藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型且任務使用 EC2 啟動類型，則**百分比上限**值會設定為預設值。該值用於定義容器執行個體處於 `DRAINING` 狀態時，服務中保持在 `RUNNING` 狀態的任務數量上限。 對於使用藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型且任務使用 EC2 的服務，您無法指定自訂的 `maximumPercent` 值。 如果服務使用藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型，且服務中的任務使用 Fargate，則不會使用百分比上限值。在描述服務時仍會傳回該值。 `minimumHealthyPercent` 類型：整數 必要：否 如果服務使用滾動更新 (`ECS`) 部署類型，則 `minimumHealthyPercent` 表示部署期間必須保持在 `RUNNING` 狀態的服務任務數量下限。這表示為無條件進位到最接近整數的 `desiredCount` 的百分比。您可以使用此參數，而無須使用額外的叢集容量進行部署。 例如，如果服務的 `desiredCount` 為 4 項任務，且 `minimumHealthyPercent` 為 50%，`maximumPercent` 為 100%，則服務排程器會先停止兩項現有任務以釋出叢集容量，再啟動兩項新任務。 如果任何任務運作狀態不良，並且 `maximumPercent` 不允許 Amazon ECS 排程器啟動替代任務，則排程器會將 `minimumHealthyPercent` 用作限制條件，逐個停止運作狀態不佳的任務，清理容量以啟動替代任務。如需有關排程器如何取代運作狀態不良任務的詳細資訊，請參閱 [Amazon ECS 服務](ecs_services.md)。 對於*不*使用負載平衡器的服務，請考慮下列事項： + 如果服務中任務內的所有必要容器都通過了運作狀態檢查，則服務就會被視為狀態良好。 + 如果工作沒有已定義運作狀態檢查的必要容器，則服務排程器會在任務達到 `RUNNING` 狀態時等待 40 秒，然後再將任務計入運作狀態最低百分比總計。 + 如果任務有一或多個已定義運作狀態檢查的必要容器，服務排程器會等待任務達到正常狀態，然後將其計算為運作狀態最低百分比總計。當任務內的所有必要容器都通過其運作狀態檢查時，工作就會被視為狀態良好。服務排程器可以等待的時間，是由容器運作狀態檢查設定所決定。如需詳細資訊，請參閱[運作狀態檢查](task_definition_parameters.md#container_definition_healthcheck)。 對於*會*使用負載平衡器的服務，請考慮下列事項： + 如果任務沒有定義運作狀態檢查的必要容器，則服務排程器會等待負載平衡器目標群組運作狀態檢查回傳狀況良好狀態，然後將任務計算為良好狀態最低百分比總計。 + 如果工作具有已定義運作狀態檢查的必要容器，服務排程器會等待工作達到正常狀態，以及負載平衡器目標群組運作狀態檢查回傳狀況良好狀態，然後再將工作計算為最低良好狀態百分比總計。 `minimumHealthyPercent` 的複本服務預設值是 100%。使用服務排程`DAEMON`的服務`minimumHealthyPercent`預設值為 0% AWS CLI、 AWS SDKs 和 APIs，以及 50% AWS 管理主控台。 部署期間運作良好任務的最低數量等於 `desiredCount` 乘以 `minimumHealthyPercent`/100，無條件進位到最接近的整數值。 如果服務使用藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型且使用 EC2 的任務在執行中，則**運作狀態百分比下限**值會設定為預設值。該值用於定義容器執行個體處於 `DRAINING` 狀態時，服務中保持在 `RUNNING` 狀態的任務數量下限。 對於使用藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型且任務使用 EC2 的服務，您無法指定自訂的 `maximumPercent` 值。 若服務使用的是藍/綠 (`CODE_DEPLOY`) 或 `EXTERNAL` 部署類型，並且使用 Fargate 的任務在執行中，則不會使用運作狀態百分比下限值，儘管描述服務時會傳回該值。 ## 部署控制器 `deploymentController` 類型：物件 必要：否 用於服務的部署控制器。如果沒有指定部署控制器，則使用 `ECS` 控制器。如需詳細資訊，請參閱[Amazon ECS 服務](ecs_services.md)。 更新服務時，此參數不會觸發新的服務部署。 `type` 類型：字串 有效值：`ECS` \$1 `CODE_DEPLOY` \$1 `EXTERNAL` 必要：是 要使用的部署控制器類型。部署控制器有三種類型： `ECS` Amazon ECS 部署控制器支援多種部署策略：滾動更新、藍/綠、線性和金絲雀。滾動更新部署類型涉及將容器的目前執行版本取代為最新版本。藍/綠部署會建立新的環境，並一次轉移流量。線性部署會以相等的百分比增量逐漸轉移流量。Canary 部署會先轉移一小部分的流量，然後轉移剩餘的流量。調整在服務部署期間允許的運作良好任務的最小和最大數量，可以控制 Amazon ECS 在滾動式更新期間新增或移除的容器數量，如同 [deploymentConfiguration](#deploymentConfiguration) 中所指定。 `CODE_DEPLOY` 藍/綠部署類型 (`CODE_DEPLOY`) 使用 CodeDeploy 支援的藍/綠部署模式，讓您可以在傳送生產流量之前驗證新部署的服務。 `EXTERNAL` 當您想要使用任何第三方部署控制器，以完全控制 Amazon ECS 服務的部署程序時，請使用外部部署類型。 ## 任務置放 `placementConstraints` 類型： 物件陣列 必要：否 您服務的任務要使用的置放限制物件陣列。每項任務您最多可以指定 10 項限制。此限制包含任務定義中的限制以及執行時間指定的限制。如果使用 Fargate，則不支援任務置放限制條件。 更新服務時，此參數不會觸發新的服務部署。 `type` 類型：字串 必要：否 限制類型。使用 `distinctInstance` 以確保特定群組中的每個任務執行於不同的容器執行個體。使用 `memberOf`，以將選擇限制於特定群組或有效的待選項目。任務定義並不支援 `distinctInstance` 值。 `expression` 類型：字串 必要：否 限制所套用的叢集查詢語言運算式。如果限制條件類型為 `distinctInstance`，則無法指定運算式。如需詳細資訊，請參閱[建立表達式以定義 Amazon ECS 任務的容器執行個體](cluster-query-language.md)。 `placementStrategy` 類型： 物件陣列 必要：否 您服務的任務要使用的置放策略物件。每項服務您最多可以指定四項策略規則。 更新服務時，此參數不會觸發新的服務部署。 `type` 類型：字串 有效值：`random` \$1 `spread` \$1 `binpack` 必要：否 置放策略類型。`random` 置放策略會將任務隨機置放於各個可用的待選項目。`spread` 置放策略根據 `field` 參數，以平均分散的方式置放於各個可用的待選項目。`binpack` 策略會根據以 `field` 參數指定的結果，將任務置放於資源最少的可用待選項目。例如，如果您在記憶體上進行 binpack，任務會放置在剩餘記憶體最少，但仍足以執行任務的執行個體上。 `field` 類型：字串 必要：否 套用置放策略的欄位。若是 `spread` 置放策略，有效的值為 `instanceId` (或擁有相同效果的 `host`)，或任何平台以及套用至 `attribute:ecs.availability-zone` 等容器執行個體的自訂屬性。若是 `binpack` 置放策略，有效值為 `cpu` 與 `memory`。若是 `random` 置放策略，此欄位並不使用。 ## Tags (標籤) `tags` 類型： 物件陣列 必要：否 您套用到服務以協助您分類和組織的中繼資料。每個標籤皆包含由您定義的一個金鑰與一個選用值。刪除服務時，也會一併刪除標籤。服務最多可套用 50 個標籤。如需詳細資訊，請參閱[標記 Amazon ECS 資源](ecs-using-tags.md)。 更新服務時，此參數不會觸發新的服務部署。 `key` 類型：字串 長度限制：長度下限為 1。長度上限為 128。 必要：否 組成標籤的鍵值組的一部分。索引鍵是一般標籤，作用就像更特定標籤值的類別。 `value` 類型：字串 長度限制：長度下限為 0。長度上限為 256。 必要：否 組成標籤的鍵值組的選用部分。值就像標籤類別 (索引鍵) 內的描述項。 `enableECSManagedTags` 類型：布林值 有效值：`true` \$1 `false` 必要：否 指定是否對服務內的任務使用 Amazon ECS 受管標籤。如未指定任何值，則預設值為 `false`。如需詳細資訊，請參閱[將標籤用於計費](ecs-using-tags.md#tag-resources-for-billing)。 更新服務時，此參數不會觸發新的服務部署。 `propagateTags` 類型：字串 有效值：`TASK_DEFINITION` \$1 `SERVICE` 必要：否 指定是否將標籤從任務定義或服務複製到服務中的任務。如果沒有指定值，則不會複製標籤。標籤只能在建立服務期間複製到服務內的任務。若要在建立服務或任務後對任務新增標籤，請使用 `TagResource` API 動作。 更新服務時，此參數不會觸發新的服務部署。 ## 網路組態 `networkConfiguration` 類型：物件 必要：否 服務的網路組態。使用 `awsvpc` 網路模式的任務定義需要此參數，才能接收其自己的彈性網路介面，其他網路模式不支援此參數。如果使用 Fargate，則需要 `awsvpc` 網路模式。如需有關 EC2 聯網的更多資訊，請參閱[EC2 的 Amazon ECS 任務聯網選項](task-networking.md)。如需有關 Fargate 聯網的更多資訊，請參閱 [Fargate 的 Amazon ECS 任務聯網選項](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-task-networking.html)。 更新服務時，此參數會觸發新的服務部署。 `awsvpcConfiguration` 類型：物件 必要：否 代表任務或服務之子網路和安全群組的物件。 `subnets` 類型：字串陣列 必要：是 與任務或服務相關聯的子網路。根據 `awsvpcConfiguration` 限制僅能指定 16 個子網路。 `securityGroups` 類型：字串陣列 必要：否 與任務或服務相關聯的安全群組。如果您未指定安全群組，則會使用預設的 VPC 安全群組。根據 `awsvpcConfiguration` 限制僅能指定五個安全群組。 `assignPublicIP` 類型：字串 有效值：`ENABLED` \$1 `DISABLED` 必要：否 無論任務的彈性網路介面是否收到公有 IP 地址。如果未指定任何值，則會使用 `DISABLED` 的預設值。 `healthCheckGracePeriodSeconds` 類型：整數 必要：否 所謂寬限期是指 Amazon ECS 服務排程器在任務首次啟動後，會在這段期間內 (以秒為單位) 忽略運作狀態不良的 Elastic Load Balancing、VPC Lattice 與容器運作狀態檢查。如果您未指定運作狀態檢查寬限期間值，則會使用預設值 0。如果您沒有使用任何運作狀態檢查，則 `healthCheckGracePeriodSeconds` 處於未使用狀態。 若服務的任務需要一些時間來啟動及回應，您可以指定運作狀態檢查的寬限期，最長為 2,147,483,647 秒 (約 69 年)。在此期間，Amazon ECS 服務排程器會忽略運作狀態檢查狀態。此寬限期可防止服務排程器將任務標示為狀況不良並在其來得及標示前加以停止。 更新服務時，此參數不會觸發新的服務部署。 `loadBalancers` 類型： 物件陣列 必要：否 用來代表您的服務所使用之負載平衡器的負載平衡器物件。針對使用 Application Load Balancer 或 Network Load Balancer 的任務，您最多僅能連接五個目標群組到一個服務。 更新服務時，此參數會觸發新的服務部署。 建立服務之後，負載平衡器組態無法從 AWS 管理主控台變更。您可以使用 AWS Copilot AWS CloudFormation AWS CLI 或 SDK 來修改滾動`ECS`部署控制器的負載平衡器組態，而不是 AWS CodeDeploy 藍/綠或外部。當您新增、更新或移除負載平衡器組態時，Amazon ECS 會使用更新後的 Elastic Load Balancing 組態啟動新的部署。這會導致任務向負載平衡器註冊和取消註冊。我們建議您在更新 Elastic Load Balancing 組態之前，先在測試環境中驗證。如需有關如何修改組態的資訊，請參閱 *Amazon Elastic Container Service API 參考* 中的 [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html)。 針對 Application Load Balancer 和 Network Load Balancer，此物件必須包含負載平衡器目標群組 ARN、容器名稱 (這會出現在容器定義中) 和容器連接埠，以從負載平衡器存取。當此服務的任務置於容器執行個體，該容器執行個體和連接埠組合就會註冊為指定之目標群組中的目標。 `targetGroupArn` 類型：字串 必要：否 與服務相關聯的 Elastic Load Balancing 目標群組的完整 Amazon Resource Name (ARN)。 僅在使用 Application Load Balancer 或Network Load Balancer時，才指定目標群組 ARN。 `loadBalancerName` 類型：字串 必要：否 要與服務建立關聯的負載平衡器名稱。 如果您使用 Application Load Balancer 或 Network Load Balancer，請略去負載平衡器名稱參數。 `containerName` 類型：字串 必要：否 要與負載平衡器建立關聯的容器 (這會出現在容器定義中) 名稱。 `containerPort` 類型：整數 必要：否 要與負載平衡器建立關聯之容器的連接埠。此連接埠必須對應至服務中任務所使用之任務定義中的 `containerPort`。針對使用 EC2 的任務，容器執行個體必須允許傳入連接埠映射的 `hostPort` 的流量。 `role` 類型：字串 必要：否 IAM 角色的簡稱或完整 ARN，此角色允許 Amazon ECS 代您呼叫您的負載平衡器。只有在您對服務使用具有單一目標群組的負載平衡器，且您的任務定義沒有使用 `awsvpc` 網路模式時，才允許此參數。如果您指定 `role` 參數，您還必須以 `loadBalancers` 參數指定負載平衡器物件。 更新服務時，此參數不會觸發新的服務部署。 如果您指定的角色有 `/` 以外的路徑，則您必須指定完整的角色 ARN (建議項目) 或在角色名稱前加上路徑。例如，如果名稱為 `bar` 的角色有路徑 `/foo/`，則您可指定 `/foo/bar` 為角色名稱。如需詳細資訊，請參閱 *IAM 使用者指南*中的[易記名稱和路徑](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)。 若您的帳戶已建立 Amazon ECS 服務連結角色，則根據預設會為您的服務使用該角色，除非您在此處另行指定。若您的任務定義使用 awsvpc 網路模式，則服務連結角色為必要項目，此時您便不應在此處指定角色。如需詳細資訊，請參閱[使用 Amazon ECS 的服務連結角色](using-service-linked-roles.md)。 `serviceConnectConfiguration` 類型：物件 必要：否 可讓此服務探索及連線至服務，並可供命名空間內其他服務探索及連線的組態。 更新服務時，此參數會觸發新的服務部署。 如需詳細資訊，請參閱[使用 Service Connect 以利用簡稱連線 Amazon ECS 服務](service-connect.md)。 `enabled` 類型：布林值 必要：是 指定是否要搭配此服務使用 Service Connect。 `namespace` 類型：字串 必要：否 用於 Service Connect 之 AWS Cloud Map 命名空間的簡短名稱或完整 Amazon Resource Name (ARN)。命名空間必須位於與 Amazon ECS 服務和叢集相同的 AWS 區域 。命名空間的類型不會影響 Service Connect。如需詳細資訊 AWS Cloud Map，請參閱《 *AWS Cloud Map 開發人員指南*》中的[使用 服務](https://docs.aws.amazon.com/cloud-map/latest/dg/working-with-services.html)。 `services` 類型： 物件陣列 必要：否 Service Connect 服務物件的陣列。這些是其他 Amazon ECS 服務用來連線到此服務的名稱和別名 (又稱為端點)。 對於屬於命名空間成員且僅連線至命名空間內其他服務的「用戶端」Amazon ECS 服務來說，此欄位不是必要欄位。以接受傳入請求的前端應用程式為例，這些請求由連接到服務的負載平衡器傳入或透過其他方式傳入。 物件會從任務定義中選取連接埠、指派 AWS Cloud Map 服務的名稱，以及一組別名 （也稱為端點） 和連接埠，供用戶端應用程式參考此服務。 `portName` 類型：字串 必要：是 `portName` 必須符合此 Amazon ECS 服務任務定義中來自所有容器的其中一個 `portMappings` 的 `name`。 `discoveryName` 類型：字串 必要：否 `discoveryName` 是 Amazon ECS 為此 Amazon ECS AWS Cloud Map 服務建立的新服務的名稱。此名稱在 AWS Cloud Map 命名空間中必須不重複。 若沒有指定此欄位，則使用 `portName`。 `clientAliases` 類型： 物件陣列 必要：否 此 Service Connect 服務的用戶端別名清單。您可以使用這些別名，指派用戶端應用程式可使用的名稱。您可以在此清單中擁有的用戶端別名數量上限為 1。 每個別名 (「端點」) 都是其他 Amazon ECS 服務 (「用戶端」) 可用來連線至此服務的 DNS 名稱和連接埠號碼。 每個名稱和連接埠組合在命名空間內必須不重複。 這些名稱在用戶端服務的每個任務中設定，而不是在 AWS Cloud Map中設定。解析這些名稱的 DNS 請求不會離開任務，也不會計入每個彈性網路介面每秒對 DNS 請求的配額。 `port` 類型：整數 必要：是 Service Connect Proxy 的接聽連接埠號碼。此連接埠可在相同命名空間內的所有任務中使用。 若要避免在用戶端 Amazon ECS 服務中變更應用程式，請將此設定為用戶端應用程式預設使用的相同連接埠。 `dnsName` 類型：字串 必要：否 `dnsName` 是您在用戶端任務應用程式中用來連線到此服務的名稱。名稱必須是有效的 DNS 標籤。 如果未指定欄位，則預設值為 `discoveryName.namespace`。如果未指定 `discoveryName`，則會使用來自任務定義的 `portName`。 若要避免在用戶端 Amazon ECS 服務中變更應用程式，請將此設定為用戶端應用程式預設使用的相同名稱。例如，一些常見名稱為 `database`、`db`，或資料庫的小寫名稱，例如 `mysql` 或 `redis`。 `ingressPortOverride` 類型：整數 必要：否 (選用) Service Connect Proxy 接聽所用的連接埠號碼。 使用此欄位的值以略過此應用程式任務定義中指定之 `portMapping` 所指定的連接埠號碼上流量的 Proxy，然後在 Amazon VPC 安全群組中使用此值，以允許流量進入此 Amazon ECS 服務的 Proxy。 在 `awsvpc` 模式中，預設值是在此應用程式任務定義中指定之 `portMapping` 所指定的容器連接埠號碼。在 `bridge` 模式中，預設值是 Service Connect Proxy 的動態暫時性連接埠。 `logConfiguration` 類型：[LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 物件 必要：否 這會定義 Service Connect Proxy 日誌的發佈位置。在非預期事件期間使用日誌進行偵錯。此組態會在此 Amazon ECS 服務的每個任務中，設定 Service Connect Proxy 容器中的 `logConfiguration` 參數。未在任務定義中指定 Proxy 容器。 我們建議您使用與此 Amazon ECS 服務任務定義的應用程式容器相同的日誌組態。對於 FireLens，這是應用程式容器的日誌組態。這不是使用 `fluent-bit` 或 `fluentd ` 容器映像的 FireLens 日誌路由器容器。 `accessLogConfiguration` 類型：[ServiceConnectAccessLogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 物件 必要：否 Service Connect 存取記錄的組態，包括日誌格式，以及日誌是否應包含查詢字串。存取日誌會擷取對服務提出之請求的詳細資訊，包括請求模式、回應碼和時間資料。若要啟用存取日誌，您還必須在 `logConfiguration`中指定 `serviceConnectConfiguration`。 `serviceRegistries` 類型： 物件陣列 必要：否 您的服務探索組態詳細資訊。如需詳細資訊，請參閱[使用服務探索以利用 DNS 名稱連接 Amazon ECS 服務](service-discovery.md)。 更新服務時，此參數會觸發新的服務部署。 `registryArn` 類型：字串 必要：否 服務登錄檔的 Amazon Resource Name (ARN)。目前支援的服務登錄檔為 AWS Cloud Map。如需詳細資訊，請參閱 *AWS Cloud Map 開發人員指南*中的[使用服務](https://docs.aws.amazon.com/cloud-map/latest/dg/working-with-services.html)。 `port` 類型：整數 必要：否 如果您的服務探索服務指定了 SRV 記錄，則使用該連接埠值。如果已使用 `awsvpc` 網路模式和 SRV 記錄，則此欄位為必要項目。 `containerName` 類型：字串 必要：否 容器名稱值用於您的「服務探索」服務。該值已於任務定義中指定。如果服務任務指定的任務定義是使用 `bridge` 或 `host` 網路模式，您必須透過任務定義指定 `containerName` 與 `containerPort` 組合。如果服務任務指定的任務定義使用 `awsvpc`網路模式，並已使用類型 SRV DNS 記錄，您必須指定 `containerName` 和 `containerPort` 組合或 `port` 值，但不得同時指定兩者。 `containerPort` 類型：整數 必要：否 用於您的「服務探索」服務的連接埠值。該值已於任務定義中指定。如果服務任務指定的任務定義是使用 `bridge` 或 `host` 網路模式，您必須透過任務定義指定 `containerName` 與 `containerPort` 組合。如果服務任務指定的任務定義使用 `awsvpc` 網路模式，並已使用類型 SRV DNS 記錄，您必須指定 `containerName` 和 `containerPort` 組合或 `port` 值，但不得同時指定兩者。 ## 用戶端字符 `clientToken` 類型：字串 必要：否 由您提供的唯一且區分大小寫的識別符，以確保請求的等冪性。長度上限為 32 個 ASCII 字元。 ## 可用區域重新平衡 `availabilityZoneRebalancing` 類型：字串 必要：否 指出服務是否使用可用區域重新平衡。有效值為 `ENABLED` 和 `DISABLED`。 更新服務時，此參數不會觸發新的服務部署。 預設行為： + 對於新服務：如果未指定任何值，則預設值為 `DISABLED`。 + 對於現有服務：如果未指定任何值，Amazon ECS 會將該值預設為現有值。如果先前未設定任何值，Amazon ECS 會將該值設定為 `DISABLED`。 如需有關可用區域重新平衡的詳細資訊，請參閱[在可用區域之間平衡 Amazon ECS 服務](service-rebalancing.md)。 ## 磁碟區組態 `volumeConfigurations` 類型：物件 必要：否 用於為由服務管理的任務建立磁碟區的組態。只有任務定義中標記為 `configuredAtLaunch` 的磁碟區才能使用此物件進行設定。 更新服務時，此參數會觸發新的服務部署。 將 Amazon EBS 磁碟區連接至由服務管理的任務時，需要此物件。如需詳細資訊，請參閱[將 Amazon EBS 磁碟區與 Amazon ECS 搭配使用](ebs-volumes.md)。 `name` 類型：字串 必要：是 建立或更新服務時設定的磁碟區名稱。最多允許 255 個字元 (大小寫)、數字、底線 (`_`) 與連字號 (`-`)。此值必須與任務定義中指定的磁碟區名稱相符。 `managedEBSVolume` 類型：物件 必要：否 用於建立 Amazon EBS 磁碟區的磁碟區組態，這些磁碟區會連接至服務建立或更新時由服務維護的任務。每項任務連接一個磁碟區。 `encrypted` 類型：布林值 必要：否 有效值：`true`\$1`false` 指定是否加密每個建立的 Amazon EBS 磁碟區。如果您已為 的特定 開啟 Amazon EBS 加密， AWS 區域 AWS 帳戶 但將此參數設定為 `false`，則會覆寫此參數，而且磁碟區會使用預設為加密指定的 KMS 金鑰進行加密。如需有關 Amazon EBS 預設加密的詳細資訊，請參閱 *Amazon EBS User Guide* 中的 [Enable Amazon EBS encryption by default](https://docs.aws.amazon.com/ebs/latest/userguide/encryption-by-default.html)。如需有關加密連接至 Amazon ECS 任務之 Amazon EBS 磁碟區的詳細資訊，請參閱[加密儲存於連接至 Amazon ECS 任務之 Amazon EBS 磁碟區中的資料](ebs-kms-encryption.md)。 `kmsKeyId` 類型：字串 必要：否 用於 Amazon EBS 加密的 AWS Key Management Service (AWS KMS) 金鑰識別符。如果指定 `kmsKeyId`，加密狀態必須是 `true`。 使用此參數指定的金鑰會覆寫 Amazon EBS 預設金鑰，或可能已指定的任何叢集層級 KMS 金鑰 (用於 Amazon ECS 受管儲存加密)。如需詳細資訊，請參閱[加密儲存於連接至 Amazon ECS 任務之 Amazon EBS 磁碟區中的資料](ebs-kms-encryption.md)。 您可以使用下列任何方式指定 KMS 金鑰： + **金輪 ID** – 例如 `1234abcd-12ab-34cd-56ef-1234567890ab`。 + **金鑰別名** – 例如 `alias/ExampleAlias`。 + **金鑰 ARN** – 例如 `arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab`。 + **別名 ARN** – 例如 `arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias`。 AWS 會以非同步方式驗證 KMS 金鑰。因此，如果指定的 ID、別名或 ARN 無效，則動作雖顯示成功，但最終會失敗。如需詳細資訊，請參閱[對 Amazon EBS 磁碟區連接問題進行疑難排解](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshoot-ebs-volumes.html)。 `volumeType` 類型：字串 必要：否 有效值：`gp2`\$1`gp3`\$1`io1`\$1`io2`\$1`sc1`\$1`st1`\$1`standard` Amazon EBS 磁碟區類型。如需有關磁碟區類型的詳細資訊，請參閱 *Amazon EBS User Guide* 中的 [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html)。預設磁碟區類型為 `gp3`。 Fargate 任務不支援 `standard` 磁碟區類型。 `sizeInGiB` 類型：整數 必要：否 有效範圍：介於 1 到 16,384 之間的整數 EBS 磁碟區的大小 (GiB)。如果未提供快照 ID 來設定要連接的磁碟區，則必須提供大小值。如果使用快照來設定要連接的磁碟區，則預設值為快照大小。然後，您可以指定大於或等於快照大小的大小。 對於 `gp2` 與 `gp3` 磁碟區類型，有效值範圍為 1-16,384。 對於 `io1` 與 `io2` 磁碟區類型，有效值範圍為 4-16,384。 對於 `st1` 與 `sc1` 磁碟區類型，有效值範圍為 125-16,384。 對於 `standard` 磁碟區類型，有效值範圍為 1-1,024。 `snapshotId` 類型：字串 必要：否 現有 Amazon EBS 磁碟區的快照 ID，Amazon ECS 可將其用於建立要連接的新磁碟區。您必須擇一指定 `snapshotId` 或 `sizeInGiB`。 `volumeInitializationRate` 類型：整數 必要：否 從現有 Amazon EBS 磁碟區的快照擷取資料以建立要連接之新磁碟區的速率 (以 MiB/s 為單位)。只有在您指定了 `snapshotId` 時，才能指定此屬性。如需有關此磁碟區初始化速率的詳細資訊，包括支援的初始化速率範圍，請參閱 *Amazon EBS User Guide* 中的 [Initialize Amazon EBS volumes](https://docs.aws.amazon.com/ebs/latest/userguide/initalize-volume.html)。 `iops` 類型：整數 必要：否 每秒 I/O 操作的次數 (IOPS)。對 `gp3`、`io1` 和 `io2` 磁碟區而言，這代表針對磁碟區佈建的 IOPS 數量。對於 `gp2` 磁碟區，此值代表磁碟區的基準效能，以及磁碟區為爆量而累積的 I/O 額度比率。這是 `io1` 和 `io2` 磁碟區的必要參數。`gp2`、`st1`、`sc1` 或 `standard` 磁碟區不支援此參數。 對於 `gp3` 磁碟區，有效值範圍為 3,000 到 16,000。 對於 `io1` 磁碟區，有效值範圍為 100 到 64,000。 對於 `io2` 磁碟區，有效值範圍為 100 到 64,000。 `throughput` 類型：整數 必要：否 為連接至由服務維護之任務的磁碟區佈建的輸送量。 僅 `gp3` 磁碟區支援此參數。 `roleArn` 類型：字串 必要：是 基礎設施 (IAM) 角色的 Amazon Resource ARN AWS Identity and Access Management (ARN)，提供 Amazon ECS 許可來管理任務的 Amazon EBS 資源。如需詳細資訊，請參閱[Amazon ECS 基礎結構 IAM 角色](infrastructure_IAM_role.md)。 `tagSpecifications` 類型：物件 必要：否 要套用至每個 Amazon EBS 磁碟區的標籤規格。 `resourceType` 類型：字串 必要：是 有效值：`volume` 建立時要標記的資源類型。 `tags` 類型： 物件陣列 必要：否 套用至磁碟區以協助您對其進行分類與整理的中繼資料。每個標籤皆由您定義的鍵與選用值組成。`AmazonECSCreated` 與 `AmazonECSManaged` 都是 Amazon ECS 代表您新增的預留標籤，因此您最多可以指定 48 個自己的標籤。刪除磁碟區時，也會一併刪除標籤。如需詳細資訊，請參閱[標記 Amazon ECS 資源](ecs-using-tags.md)。 `key` 類型：字串 長度限制：長度下限為 1。長度上限為 128。 必要：否 組成標籤的鍵值對的一部分。索引鍵是一般標籤，作用就像更特定標籤值的類別。 `value` 類型：字串 長度限制：長度下限為 0。長度上限為 256。 必要：否 組成標籤的鍵值對的選用部分。值就像標籤類別 (索引鍵) 內的描述項。 `propagateTags` 類型：字串 有效值：`TASK_DEFINITION` \$1 `SERVICE` \$1 `NONE` 必要：否 指定是否將標籤從任務定義或服務複製到磁碟區。如果指定了 `NONE` 或未指定任何值，則不會複製標籤。 `fileSystemType` 類型：字串 必要：否 有效值：`xfs`\$1`ext3`\$1`ext4`\$1`NTFS` 磁碟區上的檔案系統類型。磁碟區的檔案系統類型決定了資料在磁碟區中的儲存與擷取方式。對於從快照建立的磁碟區，您必須指定與建立快照時磁碟區所使用的相同檔案系統類型。如果有檔案系統類型不相符，則任務將無法啟動。 Linux 的有效值為 `xfs`、ext3 與 `, and ext4`。連接至 Linux 任務之磁碟區的預設值為 `XFS`。 Windows 的有效值為 `NTFS`。連接至 Windows 任務之磁碟區的預設值為 `NTFS`。