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

# Azure Cosmos DB 連線
<a name="aws-glue-programming-etl-connect-azurecosmos-home"></a>

您可以使用 AWS Glue for Spark，在 Glue 4.0 和更新版本中使用 NoSQL API AWS 從 Azure Cosmos 資料庫讀取和寫入現有容器。您可以使用 SQL 查詢定義要從 Azure Cosmos DB 讀取的內容。您可以使用 AWS Secrets Manager 透過 Glue AWS 連線存放在 中的 Azure Cosmos 資料庫金鑰來連線至 Azure Cosmos 資料庫。

如需有關 Azure Cosmos DB for NoSQL 的詳細資訊，請參閱 [Azure 文件](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/)。

## 設定 Azure Cosmos DB 連線
<a name="aws-glue-programming-etl-connect-azurecosmos-configure"></a>

若要從 Glue AWS 連線至 Azure Cosmos 資料庫，您需要建立 Azure Cosmos 資料庫金鑰並將其存放在 AWS Secrets Manager 秘密中，然後將該秘密與 Azure Cosmos 資料庫 AWS Glue 連線建立關聯。

**先決條件：**
+ 在 Azure 中，您將需要識別或產生 Azure Cosmos 資料庫金鑰，以供 AWS Glue、 使用`cosmosKey`。如需詳細資訊，請參閱《Azure 文件》中的[安全存取 Azure Cosmos DB 中的資料](https://learn.microsoft.com/en-us/azure/cosmos-db/secure-access-to-data?tabs=using-primary-key)。

**設定連至 Azure Cosmos DB 的連線：**

1. 在 中 AWS Secrets Manager，使用您的 Azure Cosmos 資料庫金鑰建立秘密。若要在 Secrets Manager 中建立秘密，請遵循 AWS Secrets Manager 文件中[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中提供的教學課程。建立機密之後，請保留機密名稱 *secretName*，以便進行下一個步驟。
   + 在選取**鍵/值組**時，請使用 *cosmosKey* 值來建立 `spark.cosmos.accountKey` 金鑰對。

1. 在 AWS Glue 主控台中，依照中的步驟建立連線[新增 AWS Glue 連線](console-connections.md)。建立連線後，請保留連線名稱 *connectionName*，以供未來在 Glue AWS 中使用。
   + 選取**連線類型**時，請選取 Azure Cosmos DB。
   + 選取 **AWS 機密**時，請提供 *secretName*。

建立 AWS Glue Azure Cosmos 資料庫連線後，您必須先執行下列步驟，才能執行 Glue AWS 任務：
+ 授予與您的 Glue 任務相關聯的 IAM AWS 角色讀取 *secretName* 的許可。
+ 在您的 AWS Glue 任務組態中，提供 *connectionName* 作為**其他網路連線**。

## 從 Azure Cosmos DB for NoSQL 容器讀取
<a name="aws-glue-programming-etl-connect-azurecosmos-read"></a>

**先決條件：**
+ 您想要讀取的 Azure Cosmos DB for NoSQL 容器。您將需要容器的識別資訊。

  An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。
+ 設定為提供身分驗證和網路位置資訊的 AWS Glue Azure Cosmos 資料庫連線。若要取得此功能，請完成上一個程序*設定連至 Azure Cosmos DB 的連線*中的步驟。您需要 Glue AWS 連線的名稱 *connectionName*。

例如：

```
azurecosmos_read = glueContext.create_dynamic_frame.from_options(
    connection_type="azurecosmos",
    connection_options={
    "connectionName": connectionName,
    "spark.cosmos.database": cosmosDBName,
    "spark.cosmos.container": cosmosContainerName,
    }
)
```

您也可提供 SELECT SQL 查詢，以篩選傳回 DynamicFrame 的結果。您將需要設定 `query`。

例如：

```
azurecosmos_read_query = glueContext.create_dynamic_frame.from_options(
    connection_type="azurecosmos",
    connection_options={
        "connectionName": "connectionName",
        "spark.cosmos.database": cosmosDBName,
        "spark.cosmos.container": cosmosContainerName,
        "spark.cosmos.read.customQuery": "query"
    }
)
```

## 寫入 Azure Cosmos DB for NoSQL 容器
<a name="aws-glue-programming-etl-connect-azurecosmos-write"></a>

此範例會從現有的 DynamicFrame *dynamicFrame* 將資訊寫入 Azure Cosmos DB。如果容器已有資訊， AWS Glue 會從 DynamicFrame 附加資料。如果容器中的資訊與寫入的資訊具有不同的結構描述，就會發生錯誤。

**先決條件：**
+ 您想要寫入的 Azure Cosmos DB 資料表。您將需要容器的識別資訊。**您必須先建立容器，再呼叫連線方法。**

  An Azure Cosmos NoSQL 容器由資料庫和容器識別。連線至 Azure Cosmos for NoSQL API 時，您必須提供資料庫名稱 *cosmosDBName* 和容器名稱 *cosmosContainerName*。
+ 設定為提供身分驗證和網路位置資訊的 AWS Glue Azure Cosmos 資料庫連線。若要取得此功能，請完成上一個程序*設定連至 Azure Cosmos DB 的連線*中的步驟。您需要 Glue AWS 連線的名稱 *connectionName*。

例如：

```
azurecosmos_write = glueContext.write_dynamic_frame.from_options(
    frame=dynamicFrame,
    connection_type="azurecosmos",
    connection_options={
    "connectionName": connectionName,
    "spark.cosmos.database": cosmosDBName,
    "spark.cosmos.container": cosmosContainerName
)
```

## Azure Cosmos DB 連線選項參考
<a name="aws-glue-programming-etl-connect-azurecosmos-reference"></a>
+ `connectionName` – 必要。用於讀取/寫入。設定為向您的連線方法提供身分驗證和網路位置資訊的 AWS Glue Azure Cosmos 資料庫連線名稱。
+ `spark.cosmos.database` – 必要。用於讀取/寫入。有效值:資料庫名稱。Azure Cosmos DB for NoSQL 資料庫名稱。
+ `spark.cosmos.container` – 必要。用於讀取/寫入。有效值:容器名稱。Azure Cosmos DB for NoSQL 容器名稱。
+ `spark.cosmos.read.customQuery` – 用於讀取。有效值：SELECT SQL 查詢。自訂查詢以選取要讀取的文件。