你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Container class

包:
@azure/cosmos

用于按 ID 读取、替换或删除特定现有容器的作。

请参阅 容器 创建新容器，以及读取/查询所有容器;使用 .containers。

注意：所有这些作都针对固定预算进行调用。 应设计系统，以便这些调用与应用程序进行子线性缩放。 例如，在每次调用 container(id).read() 之前不要调用 item.read()，以确保容器存在;在应用程序启动时执行此作。

属性

conflicts

读取和查询给定容器冲突的作。

若要读取或删除特定冲突，请使用 .conflict(id)。
database
id
items

用于创建新项和读取/查询所有项的作

若要读取、替换或删除现有项，请使用 .item(id)。

示例

创建新项

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resource: createdItem } = await container.items.create({
  id: "<item id>",
  properties: {},
});
scripts

存储过程、触发器和用户定义的函数的所有作
url

返回资源的引用 URL。 用于在权限中链接。

方法

conflict(string, PartitionKey)

用于按 ID 读取、替换或删除特定现有 冲突。

使用 .conflicts 创建新的冲突，或查询/读取所有冲突。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const container = database.container("Test Container");

const { resource: conflict } = await container.conflict("<conflict-id>").read();
delete(RequestOptions)

删除容器

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

await client.database("<db id>").container("<container id>").delete();
deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

删除所有文档属于提供的分区键值的容器

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({
  id: "Test Container",
  partitionKey: {
    paths: ["/state"],
  },
});

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Olympia", state: "IL", isCapitol: false },
];
for (const city of cities) {
  await container.items.create(city);
}

await container.deleteAllItemsForPartitionKey("WA");
getFeedRanges()

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources: ranges } = await container.getFeedRanges();
getPartitionKeyDefinition()

首先通过查看缓存来获取分区键定义，否则通过读取集合来获取分区键定义。
getQueryPlan(string | SqlQuerySpec)
initializeEncryption()

预热容器的加密相关缓存。

示例

import { ClientSecretCredential } from "@azure/identity";
import {
  AzureKeyVaultEncryptionKeyResolver,
  CosmosClient,
  EncryptionType,
  EncryptionAlgorithm,
  ClientEncryptionIncludedPath,
  ClientEncryptionPolicy,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const credentials = new ClientSecretCredential("<tenant-id>", "<client-id>", "<app-secret>");
const keyResolver = new AzureKeyVaultEncryptionKeyResolver(credentials);
const client = new CosmosClient({
  endpoint,
  key,
  clientEncryptionOptions: {
    keyEncryptionKeyResolver: keyResolver,
  },
});
const { database } = await client.databases.createIfNotExists({ id: "<db id>" });

const paths = ["/path1", "/path2", "/path3"].map(
  (path) =>
    ({
      path: path,
      clientEncryptionKeyId: "< cek - id >",
      encryptionType: EncryptionType.DETERMINISTIC,
      encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
    }) as ClientEncryptionIncludedPath,
);
const clientEncryptionPolicy: ClientEncryptionPolicy = {
  includedPaths: paths,
  policyFormatVersion: 2,
};
const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/id"],
  },
  clientEncryptionPolicy: clientEncryptionPolicy,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.initializeEncryption();
item(string, PartitionKey)

用于按 ID 读取、替换或删除特定现有 项。

使用 .items 创建新项或查询/读取所有项。

示例

替换项

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { body: replacedItem } = await container
  .item("<item id>", "<partition key value>")
  .replace({ id: "<item id>", title: "Updated post", authorID: 5 });
read(RequestOptions)

读取容器的定义

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resource: database } = await client.database("<db id>").container("<container id>").read();
readOffer(RequestOptions)

获取容器上的产品/服务。 如果不存在，则返回未定义的 OfferResponse。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resource: offer } = await client
  .database("<db id>")
  .container("<container id>")
  .readOffer();
readPartitionKeyRanges(FeedOptions)

获取容器的分区键范围。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources: ranges } = await container.readPartitionKeyRanges().fetchAll();
replace(ContainerDefinition, RequestOptions)

替换容器的定义

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/key1"],
  },
  throughput: 1000,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

containerDefinition.throughput = 400;
const { container: replacedContainer } = await container.replace(containerDefinition);
semanticRerank(string, string[], SemanticRerankOptions)

通过 Cosmos DB 推理服务，使用语义重排序对文档列表进行重新排序。 该方法使用语义重排序器，根据文档与特定上下文的相关性对其进行评分和重新排序。

语义重新排序请求使用与主 Cosmos DB 客户端分开的 HTTP 流水线，不使用 SDK 默认的重试策略。

要使用此功能，必须满足以下条件：

  1. 通过 aadCredentials 配置 AAD 认证 CosmosClientOptions
  2. 通过 给出推理端点enablePreviewFeatures.semanticRerank.inferenceEndpointCosmosClientOptions

示例

查询结果的语义重排序

import { DefaultAzureCredential } from "@azure/identity";
import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const aadCredentials = new DefaultAzureCredential();
const client = new CosmosClient({
  endpoint,
  aadCredentials,
  enablePreviewFeatures: {
    semanticRerank: {
      inferenceEndpoint: "https://your-account.<region>.dbinference.azure.com",
    },
  },
});

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryResults = ["doc1 JSON", "doc2 JSON", "doc3 JSON"];
const result = await container.semanticRerank(
  "most economical with multiple adjustments",
  queryResults,
  { return_documents: true, top_k: 10, sort: true },
);
// Access the top-ranked document
if (result.rerankScores.length > 0) {
  const topResult = result.rerankScores[0];
  const topScore = topResult.score;
  const topDocument = topResult.document;
  if (topDocument) {
    console.log("Top-ranked document:", topDocument);
  }
  console.log("Top score:", topScore);
}

属性详细信息

conflicts

读取和查询给定容器冲突的作。

若要读取或删除特定冲突，请使用 .conflict(id)。

Conflicts conflicts

属性值

Conflicts

database 

database: Database

属性值

Database

id 

id: string

属性值

string

items

用于创建新项和读取/查询所有项的作

若要读取、替换或删除现有项，请使用 .item(id)。

示例

创建新项

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resource: createdItem } = await container.items.create({
  id: "<item id>",
  properties: {},
});

Items items

属性值

Items

scripts

存储过程、触发器和用户定义的函数的所有作

Scripts scripts

属性值

Scripts

url

返回资源的引用 URL。 用于在权限中链接。

string url

属性值

string

方法详细信息

conflict(string, PartitionKey)

用于按 ID 读取、替换或删除特定现有 冲突。

使用 .conflicts 创建新的冲突，或查询/读取所有冲突。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const container = database.container("Test Container");

const { resource: conflict } = await container.conflict("<conflict-id>").read();

function conflict(id: string, partitionKey?: PartitionKey): Conflict

参数

id

string

冲突的 ID。

partitionKey
PartitionKey

返回

Conflict

delete(RequestOptions)

删除容器

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

await client.database("<db id>").container("<container id>").delete();

function delete(options?: RequestOptions): Promise<ContainerResponse>

参数

options
RequestOptions

返回

Promise<ContainerResponse>

deleteAllItemsForPartitionKey(PartitionKey, RequestOptions)

删除所有文档属于提供的分区键值的容器

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({
  id: "Test Container",
  partitionKey: {
    paths: ["/state"],
  },
});

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Olympia", state: "IL", isCapitol: false },
];
for (const city of cities) {
  await container.items.create(city);
}

await container.deleteAllItemsForPartitionKey("WA");

function deleteAllItemsForPartitionKey(partitionKey: PartitionKey, options?: RequestOptions): Promise<ContainerResponse>

参数

partitionKey
PartitionKey

要删除的项的分区键值

options
RequestOptions

返回

Promise<ContainerResponse>

getFeedRanges()

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources: ranges } = await container.getFeedRanges();

function getFeedRanges(): Promise<readonly FeedRange[]>

返回

Promise<readonly FeedRange[]>

可以提取更改源的所有源范围。

getPartitionKeyDefinition()

警告

现已弃用此 API。

This method has been renamed to readPartitionKeyDefinition.

首先通过查看缓存来获取分区键定义，否则通过读取集合来获取分区键定义。

function getPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>>

返回

Promise<ResourceResponse<PartitionKeyDefinition>>

getQueryPlan(string | SqlQuerySpec) 

function getQueryPlan(query: string | SqlQuerySpec): Promise<Response<PartitionedQueryExecutionInfo>>

参数

query

string | SqlQuerySpec

返回

Promise<Response<PartitionedQueryExecutionInfo>>

initializeEncryption()

预热容器的加密相关缓存。

示例

import { ClientSecretCredential } from "@azure/identity";
import {
  AzureKeyVaultEncryptionKeyResolver,
  CosmosClient,
  EncryptionType,
  EncryptionAlgorithm,
  ClientEncryptionIncludedPath,
  ClientEncryptionPolicy,
} from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const credentials = new ClientSecretCredential("<tenant-id>", "<client-id>", "<app-secret>");
const keyResolver = new AzureKeyVaultEncryptionKeyResolver(credentials);
const client = new CosmosClient({
  endpoint,
  key,
  clientEncryptionOptions: {
    keyEncryptionKeyResolver: keyResolver,
  },
});
const { database } = await client.databases.createIfNotExists({ id: "<db id>" });

const paths = ["/path1", "/path2", "/path3"].map(
  (path) =>
    ({
      path: path,
      clientEncryptionKeyId: "< cek - id >",
      encryptionType: EncryptionType.DETERMINISTIC,
      encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
    }) as ClientEncryptionIncludedPath,
);
const clientEncryptionPolicy: ClientEncryptionPolicy = {
  includedPaths: paths,
  policyFormatVersion: 2,
};
const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/id"],
  },
  clientEncryptionPolicy: clientEncryptionPolicy,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

await container.initializeEncryption();

function initializeEncryption(): Promise<void>

返回

Promise<void>

item(string, PartitionKey)

用于按 ID 读取、替换或删除特定现有 项。

使用 .items 创建新项或查询/读取所有项。

示例

替换项

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { body: replacedItem } = await container
  .item("<item id>", "<partition key value>")
  .replace({ id: "<item id>", title: "Updated post", authorID: 5 });

function item(id: string, partitionKeyValue?: PartitionKey): Item

参数

id

string

项的 ID。

partitionKeyValue
PartitionKey

项 分区键的值

返回

Item

read(RequestOptions)

读取容器的定义

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resource: database } = await client.database("<db id>").container("<container id>").read();

function read(options?: RequestOptions): Promise<ContainerResponse>

参数

options
RequestOptions

返回

Promise<ContainerResponse>

readOffer(RequestOptions)

获取容器上的产品/服务。 如果不存在，则返回未定义的 OfferResponse。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

const { resource: offer } = await client
  .database("<db id>")
  .container("<container id>")
  .readOffer();

function readOffer(options?: RequestOptions): Promise<OfferResponse>

参数

options
RequestOptions

返回

Promise<OfferResponse>

readPartitionKeyRanges(FeedOptions)

获取容器的分区键范围。

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const { resources: ranges } = await container.readPartitionKeyRanges().fetchAll();

function readPartitionKeyRanges(feedOptions?: FeedOptions): QueryIterator<PartitionKeyRange>

参数

feedOptions
FeedOptions

请求的选项。

返回

QueryIterator<PartitionKeyRange>

分区键范围的迭代器。

replace(ContainerDefinition, RequestOptions)

替换容器的定义

示例

import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

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

const containerDefinition = {
  id: "Test Container",
  partitionKey: {
    paths: ["/key1"],
  },
  throughput: 1000,
};
const { container } = await database.containers.createIfNotExists(containerDefinition);

containerDefinition.throughput = 400;
const { container: replacedContainer } = await container.replace(containerDefinition);

function replace(body: ContainerDefinition, options?: RequestOptions): Promise<ContainerResponse>

参数

body
ContainerDefinition
options
RequestOptions

返回

Promise<ContainerResponse>

semanticRerank(string, string[], SemanticRerankOptions)

注意

此 API 以 Beta 版本预览形式提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

通过 Cosmos DB 推理服务，使用语义重排序对文档列表进行重新排序。 该方法使用语义重排序器，根据文档与特定上下文的相关性对其进行评分和重新排序。

语义重新排序请求使用与主 Cosmos DB 客户端分开的 HTTP 流水线，不使用 SDK 默认的重试策略。

要使用此功能，必须满足以下条件：

  1. 通过 aadCredentials 配置 AAD 认证 CosmosClientOptions
  2. 通过 给出推理端点enablePreviewFeatures.semanticRerank.inferenceEndpointCosmosClientOptions

示例

查询结果的语义重排序

import { DefaultAzureCredential } from "@azure/identity";
import { CosmosClient } from "@azure/cosmos";

const endpoint = "https://your-account.documents.azure.com";
const aadCredentials = new DefaultAzureCredential();
const client = new CosmosClient({
  endpoint,
  aadCredentials,
  enablePreviewFeatures: {
    semanticRerank: {
      inferenceEndpoint: "https://your-account.<region>.dbinference.azure.com",
    },
  },
});

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

const queryResults = ["doc1 JSON", "doc2 JSON", "doc3 JSON"];
const result = await container.semanticRerank(
  "most economical with multiple adjustments",
  queryResults,
  { return_documents: true, top_k: 10, sort: true },
);
// Access the top-ranked document
if (result.rerankScores.length > 0) {
  const topResult = result.rerankScores[0];
  const topScore = topResult.score;
  const topDocument = topResult.document;
  if (topDocument) {
    console.log("Top-ranked document:", topDocument);
  }
  console.log("Top score:", topScore);
}

function semanticRerank(rerankContext: string, documents: string[], options?: SemanticRerankOptions): Promise<SemanticRerankResult>

参数

rerankContext

string

用于重新排序文档的上下文（例如查询字符串）。

documents

string[]

一份需要重新排序的文档列表（以JSON字符串形式）。

options
SemanticRerankOptions

可选的设置词典用于重新排名请求。 已知的服务选项：

  • return_documents （布林）——在回复中包含重新排序的文件。
  • top_k （编号）——可归还的最高排名文件数量。
  • batch_size （编号）——用于处理文件的批次大小。
  • sort （布尔值）——按相关性分数从低排序结果。
  • document_type （"string" | "json"） —— 被重新排序的文件类型。
  • target_paths （字符串）——逗号分隔的JSON路径（当document_type为 "json"时）。
  • abortSignal （中止信号）——发出取消请求的信号。 任何额外的密钥都会转发 as-is 推理服务。

返回

Promise<SemanticRerankResult>

重新排序结果包括评分文档、延迟和令牌使用情况。