通过 Gremlin SDK 使用 Azure Cosmos DB 资源令牌Use Azure Cosmos DB resource tokens with the Gremlin SDK

本文介绍如何通过 Gremlin SDK 使用 Azure Cosmos DB 资源令牌访问图形数据库。This article explains how to use Azure Cosmos DB resource tokens to access the Graph database through the Gremlin SDK.

创建资源令牌Create a resource token

Apache TinkerPop Gremlin SDK 没有用于创建资源令牌的 API。The Apache TinkerPop Gremlin SDK doesn't have an API to use to create resource tokens. 术语“资源令牌” 是一个 Azure Cosmos DB 概念。The term resource token is an Azure Cosmos DB concept. 若要创建资源令牌,请下载 Azure Cosmos DB SDKTo create resource tokens, download the Azure Cosmos DB SDK. 如果你的应用程序需要创建资源令牌并使用它们来访问图形数据库,则需要两个单独的 SDK。If your application needs to create resource tokens and use them to access the Graph database, it requires two separate SDKs.

下面的大纲演示了资源标记之上的对象模型层次结构:The object model hierarchy above resource tokens is illustrated in the following outline:

  • Azure Cosmos DB 帐户 - 具有关联 DNS 的顶级实体(例如,contoso.gremlin.cosmos.azure.cn)。Azure Cosmos DB account - The top-level entity that has a DNS associated with it (for example, contoso.gremlin.cosmos.azure.cn).
    • Azure Cosmos DB 数据库Azure Cosmos DB database
      • UserUser
        • 权限 Permission
          • 令牌 - 表示允许或拒绝哪些操作的权限对象属性。Token - A Permission object property that denotes what actions are allowed or denied.

资源令牌使用以下格式:"type=resource&ver=1&sig=<base64 string>;<base64 string>;"A resource token uses the following format: "type=resource&ver=1&sig=<base64 string>;<base64 string>;". 此字符串对于客户端是不透明的,应按原样使用,而无任何修改或解释。This string is opaque for the clients and should be used as is, without modification or interpretation.

// Notice that document client is created against .NET SDK endpoint, rather than Gremlin.
DocumentClient client = new DocumentClient(
  new Uri("https://contoso.documents.azure.cn:443/"), 
  "<master key>", 
  new ConnectionPolicy 
  {
    EnableEndpointDiscovery = false, 
    ConnectionMode = ConnectionMode.Direct 
  });

  // Read specific permission to obtain a token.
  // The token isn't returned during the ReadPermissionReedAsync() call.
  // The call succeeds only if database id, user id, and permission id already exist. 
  // Note that <database id> is not a database name. It is a base64 string that represents the database identifier, for example "KalVAA==".
  // Similar comment applies to <user id> and <permission id>.
  Permission permission = await client.ReadPermissionAsync(UriFactory.CreatePermissionUri("<database id>", "<user id>", "<permission id>"));

  Console.WriteLine("Obtained token {0}", permission.Token);
}

使用资源令牌Use a resource token

构造 GremlinServer 类时,可以将资源令牌直接用作“password”属性。You can use resource tokens directly as a "password" property when you construct the GremlinServer class.

// The Gremlin application needs to be given a resource token. It can't discover the token on its own.
// You can obtain the token for a given permission by using the Azure Cosmos DB SDK, or you can pass it into the application as a command line argument or configuration value.
string resourceToken = GetResourceToken();

// Configure the Gremlin server to use a resource token rather than a master key.
GremlinServer server = new GremlinServer(
  "contoso.gremlin.cosmos.azure.cn",
  port: 443,
  enableSsl: true,
  username: "/dbs/<database name>/colls/<collection name>",

  // The format of the token is "type=resource&ver=1&sig=<base64 string>;<base64 string>;".
  password: resourceToken);

  using (GremlinClient gremlinClient = new GremlinClient(server, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType))
  {
      await gremlinClient.SubmitAsync("g.V().limit(1)");
  }

这种方法在所有 TinkerPop Gremlin SDK 中都有效。The same approach works in all TinkerPop Gremlin SDKs.

Cluster.Builder builder = Cluster.build();

AuthProperties authenticationProperties = new AuthProperties();
authenticationProperties.with(AuthProperties.Property.USERNAME,
    String.format("/dbs/%s/colls/%s", "<database name>", "<collection name>"));

// The format of the token is "type=resource&ver=1&sig=<base64 string>;<base64 string>;".
authenticationProperties.with(AuthProperties.Property.PASSWORD, resourceToken);

builder.authProperties(authenticationProperties);

限制Limit

使用单个 Gremlin 帐户,可以颁发无限数量的令牌。With a single Gremlin account, you can issue an unlimited number of tokens. 但是,在 1 小时内最多只能同时使用 100 个令牌。However, you can use only up to 100 tokens concurrently within 1 hour. 如果应用程序超过每小时令牌限制,身份验证请求将被拒绝,你将收到以下错误消息:“超出了允许的资源令牌限制,最多可以同时使用 100 个。”If an application exceeds the token limit per hour, an authentication request is denied, and you receive the following error message: "Exceeded allowed resource token limit of 100 that can be used concurrently." 关闭使用特定令牌的活动连接以便为新令牌释放槽不起作用。It doesn't work to close active connections that use specific tokens to free up slots for new tokens. Azure Cosmos DB Gremlin 数据库引擎在身份验证请求之前的一小时内跟踪唯一令牌。The Azure Cosmos DB Gremlin database engine keeps track of unique tokens during the hour immediately prior to the authentication request.

权限Permission

应用程序在使用资源令牌时遇到的常见错误是“授权标头中为相应请求提供的权限不足。A common error that applications encounter while they're using resource tokens is, "Insufficient permissions provided in the authorization header for the corresponding request. 请使用另一个授权标头重试”。Please retry with another authorization header." 当 Gremlin 遍历尝试写入边缘或顶点但资源令牌仅授予“读取” 权限时,会返回此错误。This error is returned when a Gremlin traversal attempts to write an edge or a vertex but the resource token grants Read permissions only. 检查遍历是否包含以下任何步骤:.addV() 、.addE() 、.drop() 或 .property() 。Inspect your traversal to see whether it contains any of the following steps: .addV(), .addE(), .drop(), or .property().

后续步骤Next steps