オンライン アカウントに接続する

  • 9 分

クライアント ライブラリがインポートされたら、プロジェクト内の名前空間とクラスの使用を開始できます。

名前空間をインポートする

ライブラリを使用する前に、ディレクティブを使用して Microsoft.Azure.Cosmos 名前空間をインポートする必要があります。 using ディレクティブを使用すると、すべての型を強制的に完全修飾することなく、名前空間内の型を使用できます。

using Microsoft.Azure.Cosmos;

CosmosClient クラスを使用する

CosmosClient クラスのインスタンスを作成するには、認証に Azure Entra ID マネージド ID を使用することをお勧めします。 この方法により、接続文字列やキーなどのシークレットを管理する必要がなくなり、セキュリティが強化されます。

マネージド ID を使用して認証するために、次の方法を使用して CosmosClient クラスをインスタンス化できます。

  • Azure Cosmos DB アカウントのエンドポイントと Microsoft Entra ID 資格情報を受け取るコンストラクター。

Microsoft Entra マネージド ID での使用

CosmosClient クラスは、マネージド ID を介して Microsoft Entra ID 認証を使用するように構成できるため、接続文字列やアカウント キーは不要になります。 マネージド ID は、Azure でホストされるリソースに対する安全で最新の認証方法です。

using Azure.Identity;
using Microsoft.Azure.Cosmos;

// Configure the account endpoint
string accountEndpoint = "https://<youraccountname>.documents.azure.com:443/";

// Use DefaultAzureCredential for Azure Entra Managed Identity authentication
DefaultAzureCredential credential = new DefaultAzureCredential();

// Initialize CosmosClient with the endpoint and Azure Entra Managed Identity
CosmosClient client = new CosmosClient(accountEndpoint, credential);

アカウントのプロパティを読み取る

ヒント

この時点では、Azure Cosmos DB for NoSQL アカウントの論理クライアント側の表現のみがあります。 操作を実行するまで、SDK は最初にアカウントに接続しません。

クライアント インスタンスのインスタンスが作成されると、さまざまなメソッドを直接使用できます。 たとえば、ReadAccountAsync メソッドを非同期に呼び出して、さまざまなプロパティを持つ AccountProperties 型のオブジェクトを取得できます。

AccountProperties account = await client.ReadAccountAsync();

AccountProperties クラスには、次のような便利なプロパティが含まれていますが、これらに限定されません。

プロパティ 説明
身分証明書 アカウントの一意の名前を取得します
ReadableRegions アカウントの読み取り可能な場所の一覧を取得します
書き込み可能な領域 アカウントの書き込み可能な場所の一覧を取得します
一貫性 アカウントの既定の整合性レベルを取得します

データベースを操作する

クライアント インスタンスを作成したら、次の 3 つの方法のいずれかを使用してデータベースを取得または作成できます。

  • 名前を使用して既存のデータベースを取得する
  • 一意のデータベース名を渡す新しいデータベースを作成する
  • SDK でデータベースの存在を確認し、自動的に作成または取得するようにします

これら 3 つの方法ではいずれも、データベースの操作に使用できる Database 型のインスタンスが返されます。

既存のデータベースを取得する

Database database = client.GetDatabase("cosmicworks");

新しいデータベースの作成

Database database = await client.CreateDatabaseAsync("cosmicworks");

データベースがまだ存在しない場合は作成する

Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");

コンテナーを操作する

データベース インスタンスを作成したので、次の 3 つの方法のいずれかを使用してコンテナーを取得または作成できます。

  • 名前だけを使用して既存のコンテナーを取得します。
  • 一意のコンテナー名、パーティション キーのパス、手動でプロビジョニングするスループットの量を渡す新しいコンテナーを作成します。
  • SDK でコンテナーの存在を確認し、自動的に作成または取得するようにします。

これら 3 つの方法ではいずれも、コンテナーの操作に使用できる Container 型のインスタンスが返されます。

既存のコンテナーを取得する

Container container = database.GetContainer("products");

新しいコンテナーを作成する

Container container = await database.CreateContainerAsync(
    new ContainerProperties(chatContainerName, "/categoryId"), 
    ThroughputProperties.CreateAutoscaleThroughput(1000)
);

コンテナーがまだ存在しない場合は作成する

Container container = await database.CreateContainerIfNotExistsAsync(
    new ContainerProperties(chatContainerName, "/categoryId"), 
    ThroughputProperties.CreateAutoscaleThroughput(1000)
);

ライブラリをインポートする

ライブラリを使用する前に、azure.cosmos モジュールから CosmosClient およびその他の必要なクラスをインポートする必要があります。 これらのクラスをインポートすると、各型を完全に修飾しなくても型にアクセスできます。

from azure.cosmos import CosmosClient, PartitionKey, ThroughputProperties, ContainerProxy, exceptions

CosmosClient クラスを使用する

CosmosClient クラスのインスタンスを作成する最も一般的な 3 つの方法は、次の 3 つのコンストラクターのいずれかを使用してインスタンス化することです。

  • アカウントの接続文字列を表す 1 つの文字列値を受け取るコンストラクター。
  • エンドポイントを表す 2 つの文字列値とアカウントのキーを受け取るコンストラクター。
  • エンドポイントを表す文字列値と、Microsoft Entra ID 認証を有効にするトークン資格情報を受け取るコンストラクター。

注

接続文字列、エンドポイント、または任意のキーは、Azure portal からいつでも取得できます。 このセクションの例では、https://dp420.documents.azure.com:443/ の架空のエンドポイントと fDR2ci9QgkdkvERTQ== のサンプル キーを使用します。

ヒント

Microsoft Entra ID 認証に直接 Microsoft ID プラットフォームで CosmosClient クラスを使用することは、ベスト プラクティスと見なされます。 詳細については、Azure Cosmos DB for NoSQL の セキュリティ ガイダンスを参照してください。

接続文字列で使用する

CosmosClient クラスは、接続文字列を渡すことによってインスタンス化できます。 この例では、AccountEndpoint=<account-endpoint>;AccountKey=<account-key>形式の接続文字列を使用します。

connection_string = "AccountEndpoint=https://dp420.documents.azure.com:443/;AccountKey=fDR2ci9QgkdkvERTQ=="

client = CosmosClient.from_connection_string(connection_string)

エンドポイントとキーで使用する

または、エンドポイントとキーを 2 つの個別のパラメーターとして指定して、CosmosClient クラスのインスタンスを作成することもできます。

endpoint = "https://dp420.documents.azure.com:443/"
key = "fDR2ci9QgkdkvERTQ=="

client = CosmosClient(endpoint, key)

エンドポイントとトークン資格情報で使用する

CosmosClient クラスのコンストラクターを使用して、エンドポイント と トークン資格情報を受け取ることもできます。 このコンストラクターは、Microsoft Entra ID を使用して認証する場合に使用されます。 この例では、架空のエンドポイントとトークン資格情報を使用します。

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://dp420.documents.azure.com:443/"

client = CosmosClient(url=endpoint, credential=credential)

アカウントのプロパティを読み取る

ヒント

この時点で、クライアント インスタンスは Azure Cosmos DB アカウントの論理表現にすぎません。 操作を実行するまで、接続は行われません。

クライアント インスタンスが作成されたら、それを使用してさまざまな操作を実行できます。 たとえば、client.get_database_account() メソッドを使用して、アカウントのプロパティにアクセスできます。

account_info = client.get_database_account()

account_info オブジェクトは、次のような便利なプロパティを含む DatabaseAccountのインスタンスを表します。

プロパティ 説明
EnableMultipleWritableLocations の 複数の場所で書き込みを行うことができるかどうかを示す Azure Cosmos アカウントにフラグを設定する
ReadableLocations アカウントの読み取り可能な場所の一覧
WritableLocations アカウントの書き込み可能な場所の一覧
ConsistencyPolicy アカウントの既定の整合性レベル

データベースを操作する

クライアント インスタンスを作成したら、次の 3 つの方法のいずれかを使用してデータベースを取得または作成できます。

  • 名前を使用して既存のデータベースを取得します。
  • 一意のデータベース名を渡して、新しいデータベースを作成します。
  • データベースが存在するかどうかを確認し、データベースを自動的に作成または取得します。

これらのメソッドは、データベースとの対話に使用できる DatabaseProxy インスタンスを返します。

既存のデータベースを取得する

database = client.get_database_client("cosmicworks")

新しいデータベースの作成

database = client.create_database("cosmicworks")

データベースがまだ存在しない場合は作成する

database = client.create_database_if_not_exists("cosmicworks")

コンテナーを操作する

データベース インスタンスでは、次のいずれかの方法を使用してコンテナーを取得または作成できます。

  • 名前で既存のコンテナーを取得します。
  • 一意のコンテナー名、パーティション キー パス、および手動でプロビジョニングされたスループットを指定して、新しいコンテナーを作成します。
  • コンテナーが存在するかどうかを確認し、コンテナーを自動的に作成または取得します。

各メソッドは、コンテナーとの対話に使用できる ContainerProxy インスタンスを返します。

既存のコンテナーを取得する

container = database.get_container_client("products")

新しいコンテナーを作成する

container = database.create_container(
    id="products",
    partition_key=PartitionKey(path="/categoryId"),
    throughput=ThroughputProperties(auto_scale_max_throughput=1000)
)

コンテナーがまだ存在しない場合は作成する

container = database.create_container_if_not_exists(
    id="products",
    partition_key=PartitionKey(path="/categoryId"),
    offer_throughput=ThroughputProperties(auto_scale_max_throughput=1000)
)

ライブラリをインポートする

ライブラリを使用する前に、CosmosClient およびその他の必要なクラスを @azure/cosmos パッケージからインポートする必要があります。 これらのクラスをインポートすると、各型を完全に修飾しなくても型にアクセスできます。

const { CosmosClient, Database, Container } = require("@azure/cosmos");

CosmosClient クラスを使用する

CosmosClient クラスのインスタンスを作成する最も一般的な 3 つの方法は、次の 3 つのコンストラクターのいずれかを使用してインスタンス化することです。

  • アカウントの接続文字列を表す 1 つの文字列値を受け取るコンストラクター。
  • エンドポイントを表す 2 つの文字列値とアカウントのキーを受け取るコンストラクター。
  • エンドポイントを表す文字列値と、Microsoft Entra ID 認証を有効にするトークン資格情報を受け取るコンストラクター。

注

接続文字列、エンドポイント、または任意のキーは、Azure portal からいつでも取得できます。 このセクションの例では、https://dp420.documents.azure.com:443/ の架空のエンドポイントと fDR2ci9QgkdkvERTQ== のサンプル キーを使用します。

ヒント

Microsoft Entra ID 認証に直接 Microsoft ID プラットフォームで CosmosClient クラスを使用することは、ベスト プラクティスと見なされます。 詳細については、Azure Cosmos DB for NoSQL の セキュリティ ガイダンスを参照してください。

接続文字列で使用する

CosmosClient クラスは、接続文字列を渡すことによってインスタンス化できます。 この例では、AccountEndpoint=<account-endpoint>;AccountKey=<account-key>形式の接続文字列を使用します。

const connectionString = "AccountEndpoint=https://dp420.documents.azure.com:443/;AccountKey=fDR2ci9QgkdkvERTQ==";

const client = new CosmosClient({ connectionString });

エンドポイントとキーで使用する

または、エンドポイントとキーを 2 つの個別のパラメーターとして指定して、CosmosClient クラスのインスタンスを作成することもできます。

const endpoint = "https://dp420.documents.azure.com:443/";
const key = "fDR2ci9QgkdkvERTQ==";

const client = new CosmosClient({ endpoint, key });

エンドポイントとキーで使用する

CosmosClient クラスのコンストラクターを使用して、エンドポイント と トークン資格情報を受け取ることもできます。 このコンストラクターは、Microsoft Entra ID を使用して認証する場合に使用されます。 この例では、架空のエンドポイントとトークン資格情報を使用します。

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const endpoint = "https://dp420.documents.azure.com:443/";

const client = new CosmosClient({ endpoint, aadCredentials: credential });

アカウントのプロパティを読み取る

ヒント

この時点で、クライアント インスタンスは Azure Cosmos DB アカウントの論理表現にすぎません。 操作を実行するまで、接続は行われません。

クライアント インスタンスが作成されたら、それを使用してさまざまな操作を実行できます。 たとえば、getDatabaseAccount メソッドを使用してアカウントプロパティを取得できます。

async function readAccountProperties() {
    const { resource: accountInfo } = await client.getDatabaseAccount();
    console.log(accountInfo);
}

readAccountProperties().catch((error) => console.error(error));

accountInfo オブジェクトは、次のような便利なプロパティを含む、DatabaseAccountのインスタンスを表します。

プロパティ 説明
enableMultipleWritableLocations を する 複数の場所で書き込みを行うことができるかどうかを示す Azure Cosmos アカウントにフラグを設定する
readableLocations を する アカウントの読み取り可能な場所の一覧
書き込み可能な場所 アカウントの書き込み可能な場所の一覧
consistencyPolicy アカウントの既定の整合性レベル

データベースを操作する

クライアント インスタンスを作成したら、次の 3 つの方法のいずれかを使用してデータベースを取得または作成できます。

  • 名前を使用して既存のデータベースを取得します。
  • 一意のデータベース名を渡して、新しいデータベースを作成します。
  • データベースが存在するかどうかを確認し、データベースを自動的に作成または取得します。

これらのメソッドは、データベースとの対話に使用できる Database インスタンスを返します。

既存のデータベースを取得する

const database = client.database("cosmicworks");

新しいデータベースの作成

const { resource: database } = await client.databases.createIfNotExists({ id: "cosmicworks" });

データベースがまだ存在しない場合は作成する

const { resource: database } = await client.databases.createIfNotExists({ id: "cosmicworks" });

コンテナーを操作する

データベース インスタンスでは、次のいずれかの方法を使用してコンテナーを取得または作成できます。

  • 名前で既存のコンテナーを取得します。
  • 一意のコンテナー名、パーティション キー パス、および手動でプロビジョニングされたスループットを指定して、新しいコンテナーを作成します。
  • コンテナーが存在するかどうかを確認し、コンテナーを自動的に作成または取得します。

各メソッドは、コンテナーと対話するために使用できる Container インスタンスを返します。

既存のコンテナーを取得する

const container = database.container("products");

新しいコンテナーを作成する

const { resource: container } = await database.containers.create({
    id: "products",
    partitionKey: {
        paths: ["/categoryId"]
    },
    maxThroughput: 1000
});

コンテナーがまだ存在しない場合は作成する

const { resource: container } = await database.containers.createIfNotExists({
    id: "products",
    partitionKey: {
        paths: ["/categoryId"]
    },
    maxThroughput: 1000
});