配置跨源资源共享 (CORS)Configure Cross-Origin Resource Sharing (CORS)

跨源资源共享 (CORS) 是一项 HTTP 功能,使在一个域中运行的 Web 应用程序能够访问另一个域中的资源。Cross-Origin Resource Sharing (CORS) is an HTTP feature that enables a web application running under one domain to access resources in another domain. Web 浏览器实施一种称为“同源策略”的安全限制,防止网页调用不同域中的 API。Web browsers implement a security restriction known as same-origin policy that prevents a web page from calling APIs in a different domain. 但是,CORS 提供了一种安全的方式,允许源域调用另一个域中的 API。However, CORS provides a secure way to allow the origin domain to call APIs in another domain. Azure Cosmos DB 中的 Core (SQL) API 现在通过使用“allowedOrigins”标头来支持跨域资源共享 (CORS)。The Core (SQL) API in Azure Cosmos DB now supports Cross-Origin Resource Sharing (CORS) by using the "allowedOrigins" header. 为 Azure Cosmos 帐户启用 CORS 支持后,仅对经过身份验证的请求进行评估,以根据指定的规则确定是否允许这些请求。After you enable the CORS support for your Azure Cosmos account, only authenticated requests are evaluated to determine whether they are allowed according to the rules you have specified.

可以使用 Azure 门户或 Azure 资源管理器模板配置跨源资源共享 (CORS) 设置。You can configure the Cross-origin resource sharing (CORS) setting from the Azure portal or from an Azure Resource Manager template. 对于使用 Core (SQL) API 的 Cosmos 帐户,Azure Cosmos DB 支持在 Node.js 和基于浏览器的环境中均可使用的 JavaScript 库。For Cosmos accounts using the Core (SQL) API, Azure Cosmos DB supports a JavaScript library that works in both Node.js and browser-based environments. 使用网关模式时,该库现在可以充分利用 CORS 支持。This library can now take advantage of CORS support when using Gateway mode. 无需客户端配置即可使用此功能。There is no client-side configuration needed to use this feature. 借助 CORS 支持,来自浏览器的资源可以通过 JavaScript 库直接访问 Azure Cosmos DB 或直接通过 REST API 进行访问来执行简单操作。With CORS support, resources from a browser can directly access Azure Cosmos DB through the JavaScript library or directly from the REST API for simple operations.

Note

CORS 支持仅适用于 Azure Cosmos DB Core (SQL) API 并受其支持。CORS support is only applicable and supported for the Azure Cosmos DB Core (SQL) API. 它不适用于用于 Cassandra、Gremlin 或 MongoDB 的 Azure Cosmos DB API,因为这些协议不使用 HTTP 进行客户端-服务器通信。It is not applicable to the Azure Cosmos DB APIs for Cassandra, Gremlin, or MongoDB, as these protocols do not use HTTP for client-server communication.

通过 Azure 门户启用 CORS 支持Enable CORS support from Azure portal

使用以下步骤通过 Azure 门户启用跨源资源共享:Use the following steps to enable Cross-Origin Resource Sharing by using Azure portal:

  1. 导航到 Azure Cosmos DB 帐户。Navigate to your Azure cosmos DB account. 打开“CORS” 边栏选项卡。Open the CORS blade.

  2. 指定可以对 Azure Cosmos DB 帐户执行跨源调用的源的逗号分隔列表。Specify a comma-separated list of origins that can make cross-origin calls to your Azure Cosmos DB account. 例如:https://www.mydomain.comhttps://mydomain.comhttps://api.mydomain.comFor example, https://www.mydomain.com, https://mydomain.com, https://api.mydomain.com. 还可以使用通配符“*”允许所有源,然后选择“提交” 。You can also use a wildcard "*" to allow all origins and select Submit.

    Note

    目前,不能将通配符用作域名的一部分。Currently, you cannot use wildcards as part of the domain name. 例如,尚不支持 https://*.mydomain.net 格式。For example https://*.mydomain.net format is not yet supported.

    使用 Azure 门户启用跨源资源共享

使用资源管理器模板启用 CORS 支持Enable CORS support from Resource Manager template

若要使用资源管理器模板启用 CORS,请将具有“allowedOrigins”属性的“cors”部分添加到任何现有模板。To enable CORS by using a Resource Manager template, add the "cors" section with "allowedOrigins" property to any existing template. 以下 JSON 是用于创建启用了 CORS 的新 Azure Cosmos 帐户的模板的示例。The following JSON is an example of a template that creates a new Azure Cosmos account with CORS enabled.

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "name": "[variables('accountName')]",
  "apiVersion": "2019-08-01",
  "location": "[parameters('location')]",
  "kind": "GlobalDocumentDB",
  "properties": {
    "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
    "locations": "[variables('locations')]",
    "databaseAccountOfferType": "Standard",
    "cors": [
      {
        "allowedOrigins": "*"
      }
    ]
  }
}

从浏览器使用 Azure Cosmos DB JavaScript 库Using the Azure Cosmos DB JavaScript library from a browser

目前,Azure Cosmos DB JavaScript 库只有 CommonJS 版本的库(随附其包)。Today, the Azure Cosmos DB JavaScript library only has the CommonJS version of the library shipped with its package. 若要从浏览器使用此库,必须使用 Rollup 或 Webpack 等工具来创建与浏览器兼容的库。To use this library from the browser, you have to use a tool such as Rollup or Webpack to create a browser compatible library. 某些 Node.js 库应具有它们的浏览器模拟。Certain Node.js libraries should have browser mocks for them. 下面是具有所需模拟设置的 webpack 配置文件的示例。The following is an example of a webpack config file that has the necessary mock settings.

const path = require("path");

module.exports = {
  entry: "./src/index.ts",
  devtool: "inline-source-map",
  node: {
    net: "mock",
    tls: "mock"
  },
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist")
  }
};

下面是将 TypeScript 和 Webpack 与 Azure Cosmos DB JavaScript SDK 库配合使用来生成创建新项时发送实时更新的 Todo 应用的代码示例Here is a code sample that uses TypeScript and Webpack with the Azure Cosmos DB JavaScript SDK library to build a Todo app that sends real time updates when new items are created. 最佳做法是,不要使用主键从浏览器与 Azure Cosmos DB 进行通信。As a best practice, do not use the primary key to communicate with Azure Cosmos DB from the browser. 而应使用资源令牌进行通信。Instead, use resource tokens to communicate. 有关资源令牌的详细信息,请参阅保护对 Azure Cosmos DB 的访问一文。For more information about resource tokens, see Securing access to Azure Cosmos DB article.

后续步骤Next steps

若要了解有关保护 Azure Cosmos 帐户的其他方式,请参阅以下文章:To learn about other ways to secure your Azure Cosmos account, see the following articles: