Administration 行政 ¶

Ocelot supports changing configuration during runtime via an authenticated HTTP API. This can be authenticated in two ways either using Ocelot’s internal IdentityServer (for authenticating requests to the administration API only) or hooking the administration API authentication into your own IdentityServer.
Ocelot 支持在运行时通过经过身份验证的 HTTP API 更改配置。这可以通过两种方式进行身份验证：使用 Ocelot 的内部 IdentityServer（仅用于验证对管理 API 的请求）或将管理 API 身份验证挂接到您自己的 IdentityServer 中。

The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package:
如果您想使用管理 API，您需要做的第一件事是引入相关的 NuGet 包：

Install-Package Ocelot.Administration

This will bring down everything needed by the administration API.
这将关闭管理 API 所需的一切。

Providing your own IdentityServer
提供你自己的 IdentityServer ¶

All you need to do to hook into your own IdentityServer is add the following configuration options with authentication to your ConfigureServices method. After that we must pass these options to AddAdministration() extension of the OcelotBuilder being returned by AddOcelot() [1] like below:
要连接到您自己的 IdentityServer，您所需要做的就是将以下带有身份验证的配置选项添加到您的 ConfigureServices 方法中。之后，我们必须将这些选项传递给 AddOcelot() [1] 返回的 OcelotBuilder 的 AddAdministration() 扩展，如下所示：

public virtual void ConfigureServices(IServiceCollection services)
{
    Action<JwtBearerOptions> options = o =>
    {
        o.Authority = identityServerRootUrl;
        o.RequireHttpsMetadata = false;
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateAudience = false,
        };
        // etc...
    };

    services
        .AddOcelot()
        .AddAdministration("/administration", options);
}

You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot’s administration API.
现在，您需要从 IdentityServer 获取令牌并在对 Ocelot 管理 API 的后续请求中使用。

This feature was implemented for Issue 228. It is useful because the IdentityServer authentication middleware needs the URL of the IdentityServer. If you are using the internal IdentityServer, it might not always be possible to have the Ocelot URL.
该功能是在第 228 期中实现的。它很有用，因为 IdentityServer 身份验证中间件需要 IdentityServer 的 URL。如果您使用内部 IdentityServer，可能并不总是可以获得 Ocelot URL。

Internal IdentityServer
内部身份服务器 ¶

The API is authenticated using Bearer tokens that you request from Ocelot itself. This is provided by the amazing Identity Server project that the .NET community has been using for several years. Check them out.
API 使用您从 Ocelot 本身请求的不记名令牌进行身份验证。这是由 .NET 社区多年来一直使用的令人惊叹的 Identity Server 项目提供的。去看一下。

In order to enable the administration section, you need to do a few things. First of all, add this to your initial Startup.cs.
为了启用管理部分，您需要做一些事情。首先，将其添加到您的初始 Startup.cs 中。

The path can be anything you want and it is obviously recommended don’t use a URL you would like to route through with Ocelot as this will not work. The administration uses the MapWhen functionality of ASP.NET Core and all requests to “{root}/administration” will be sent there not to the Ocelot middleware.
该路径可以是您想要的任何内容，显然建议不要使用您希望通过 Ocelot 路由的 URL，因为这不起作用。管理使用 ASP.NET Core 的 MapWhen 功能，所有对“{root}/administration”的请求都将发送到那里，而不是发送到 Ocelot 中间件。

The secret is the client secret that Ocelot’s internal IdentityServer will use to authenticate requests to the administration API. This can be whatever you want it to be! In order to pass this secret string as parameter, we must call the AddAdministration() extension of the OcelotBuilder being returned by AddOcelot() [1] like below:

public virtual void ConfigureServices(IServiceCollection services)
{
    services
        .AddOcelot()
        .AddAdministration("/administration", "secret");
}

In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation. This means that you need to add the base URL of Ocelot to global configuration if it is not default http://localhost:5000. Please note, if you are using something like Docker to host Ocelot it might not be able to call back to localhost etc, and you need to know what you are doing with Docker networking in this scenario. Anyway, this can be done as follows.
为了使管理 API 正常工作，Ocelot / IdentityServer 必须能够调用自身进行验证。这意味着如果 Ocelot 的基本 URL 不是默认的 http://localhost:5000 ，则需要将其添加到全局配置中。请注意，如果您使用 Docker 之类的东西来托管 Ocelot，它可能无法回调到 localhost 等，并且您需要知道在这种情况下您正在使用 Docker 网络做什么。无论如何，这可以按如下方式完成。

If you want to run on a different host and port locally:
如果您想在本地不同的主机和端口上运行：

"GlobalConfiguration": {
   "BaseUrl": "http://localhost:55580"
 }

or if Ocelot is exposed via DNS:
或者如果 Ocelot 通过 DNS 公开：

"GlobalConfiguration": {
   "BaseUrl": "http://mydns.com"
 }

Now, if you went with the configuration options above and want to access the API, you can use the Postman scripts called ocelot.postman_collection.json in the solution to change the Ocelot configuration. Obviously these will need to be changed if you are running Ocelot on a different URL to http://localhost:5000.
现在，如果您使用上述配置选项并想要访问 API，则可以使用解决方案中名为 ocelot.postman_collection.json 的 Postman 脚本来更改 Ocelot 配置。显然，如果您在与 http://localhost:5000 不同的 URL 上运行 Ocelot，则需要更改这些内容。

The scripts show you how to request a Bearer token from Ocelot and then use it to GET the existing configuration and POST a configuration.
这些脚本向您展示了如何从 Ocelot 请求承载令牌，然后使用它来获取现有配置并发布配置。

If you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the Bearer tokens used to access the administration API.
如果您在集群中运行多个 Ocelot 实例，则需要使用证书来签署用于访问管理 API 的承载令牌。

In order to do this, you need to add two more environmental variables for each Ocelot in the cluster:
为此，您需要为集群中的每个 Ocelot 添加两个环境变量：

1. OCELOT_CERTIFICATE The path to a certificate that can be used to sign the tokens. The certificate needs to be of the type X509 and obviously Ocelot needs to be able to access it.
   OCELOT_CERTIFICATE 可用于签署令牌的证书的路径。该证书的类型需要是 X509，显然 Ocelot 需要能够访问它。

2. OCELOT_CERTIFICATE_PASSWORD The password for the certificate.
   OCELOT_CERTIFICATE_PASSWORD 证书的密码。

Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. If all the other Ocelot instances in the cluster have the same certificate then you are good!
通常，Ocelot 仅使用临时签名凭据，但如果您设置这些环境变量，那么它将使用证书。如果集群中的所有其他 Ocelot 实例都具有相同的证书，那么就没有问题！

Administration API 管理 API ¶

POST {adminPath}/connect/token

This gets a token for use with the admin area using the client credentials we talk about setting above. Under the hood this calls into an IdentityServer hosted within Ocelot.
这将使用我们上面讨论的设置的客户端凭据获取用于管理区域的令牌。在底层，这会调用 Ocelot 中托管的 IdentityServer。

The body of the request is form-data as follows:
请求的正文是表单数据，如下所示：

• client_id set as admin  client_id 设置为管理员

• client_secret set as whatever you used when setting up the administration services.
  client_secret 设置为您在设置管理服务时使用的任何内容。

• scope set as admin  scope 设置为管理员

• grant_type set as client_credentials
  grant_type 设置为 client_credentials

GET {adminPath}/configuration
获取 {adminPath}/配置 ¶

This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
这将获取当前的 Ocelot 配置。它与我们最初用于设置 Ocelot 的 JSON 完全相同。

POST {adminPath}/configuration
POST {adminPath}/配置 ¶

This overwrites the existing configuration (should probably be a PUT!). We recommend getting your config from the GET endpoint, making any changes and posting it back… simples.
这会覆盖现有配置（可能应该是 PUT！）。我们建议从 GET 端点获取您的配置，进行任何更改并将其发回......很简单。

The body of the request is JSON and it is the same format as the FileConfiguration that we use to set up Ocelot on a file system.
请求的正文是 JSON，它与我们用于在文件系统上设置 Ocelot 的 FileConfiguration 的格式相同。

Please note, if you want to use this API then the process running Ocelot must have permission to write to the disk where your ocelot.json or ocelot.{environment}.json is located. This is because Ocelot will overwrite them on save.
请注意，如果您想使用此 API，则运行 Ocelot 的进程必须有权写入 ocelot.json 或 ocelot.{environment}.json 所在的磁盘。这是因为 Ocelot 会在保存时覆盖它们。

DELETE {adminPath}/outputcache/{region}

This clears a region of the cache. If you are using a backplane, it will clear all instances of the cache! Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time, so just use a distributed cache.

The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.

---

[1] (1,2)

The AddOcelot method adds default ASP.NET services to DI-container. You could call another more extended AddOcelotUsingBuilder method while configuring services to build and use custom builder via an IMvcCoreBuilder interface object. See more instructions in Dependency Injection, “The AddOcelotUsingBuilder method” section.

Simplify infrastructure with MongoDB Atlas, the leading developer data platform

Ad by EthicalAds   ·   ℹ️