[译]Ocelot

原文

Ocelot主要的功能就是将http请求转发到对应的下游服务上去。

Ocelot将一个请求路由到另外一个路由的动作叫做ReRoute。为了能让Ocelot能正常工作，需要在配置中设置ReRoute。

{
    "ReRoutes": [
    ]
}

配置ReRoute需要添加一个ReRoutes json 数组。

{
    "DownstreamPathTemplate": "/api/posts/{postId}",
    "DownstreamScheme": "https",
    "DownstreamHostAndPorts": [
            {
                "Host": "localhost",
                "Port": 80,
            }
        ],
    "UpstreamPathTemplate": "/posts/{postId}",
    "UpstreamHttpMethod": [ "Put", "Delete" ]
}

DownstreamPathTemplate, DownstreamScheme和DownstreamHostAndPorts定义请求需要转发到哪个URL上去。

DownstreamHostAndPorts是一个集合，它定义了要转发到的下游服务的host和port。通常这个集合只需要一个条目就可以了，但是如果你想要搞负载均衡的话，可以在这指定多个条目。

UpstreamPathTemplate定义了ocelot用哪个发到ocelot的请求处理DownstreamPathTemplate。Ocelot根据UpstreamHttpMethod来针对同一个URL不同请求方式分别进行对应的处理。如果没指定UpstreamHttpMethod的话，那就是针对所有的HTTP请求方式。

可以为Template中的变量添加placeholder（以{something}的形式）。placeholder变量必须同时出现在DownstreamPathTemplate和UpstreamPathTemplate中。

可以通过下面做一个通用的默认ReRoute：

{
    "DownstreamPathTemplate": "/api/{everything}",
    "DownstreamScheme": "https",
    "DownstreamHostAndPorts": [
            {
                "Host": "localhost",
                "Port": 80,
            }
        ],
    "UpstreamPathTemplate": "/{everything}",
    "UpstreamHttpMethod": [ "Get", "Post" ]
}

上面的代码会将所有的path+query组合起来发到下流服务的/api路径下。

ReRouting配置大小写不敏感。

可以通过下面的配置设置大小写敏感：

"ReRouteIsCaseSensitive": true

Catch All

如果你的配置如下，所有的请求将直接发送，上下游的url地址会完全一致。 {url}名字可以随便改，不是一个专用的名字。

{
    "DownstreamPathTemplate": "/{url}",
    "DownstreamScheme": "https",
    "DownstreamHostAndPorts": [
            {
                "Host": "localhost",
                "Port": 80,
            }
        ],
    "UpstreamPathTemplate": "/{url}",
    "UpstreamHttpMethod": [ "Get" ]
}

catch all的优先级最低。如果你有下面的一个ReRoute，那么会优先匹配这个ReRoute，而不是Catch all：

{
    "DownstreamPathTemplate": "/",
    "DownstreamScheme": "https",
    "DownstreamHostAndPorts": [
            {
                "Host": "10.0.10.1",
                "Port": 80,
            }
        ],
    "UpstreamPathTemplate": "/",
    "UpstreamHttpMethod": [ "Get" ]
}

Upstream Host

使用UpstreamHost设置基于upstream host的ReRoute。通过客户端请求的host来决定使用哪个ReRoute。

通过下面的配置使用Upstream host：

{
    "DownstreamPathTemplate": "/",
    "DownstreamScheme": "https",
    "DownstreamHostAndPorts": [
            {
                "Host": "10.0.10.1",
                "Port": 80,
            }
        ],
    "UpstreamPathTemplate": "/",
    "UpstreamHttpMethod": [ "Get" ],
    "UpstreamHost": "somedomain.com"
}

上面的ReRoute只有在host header的值为somedomain.com的时候才会匹配到。

Priority

可以通过Priority定义ReRoute的匹配的优先级别。

{
    "Priority": 0
}

0是最低的优先级别。Ocelot会为 /{catchAll} ReRoute 使用 0这个优先级别。

{
    "UpstreamPathTemplate": "/goods/{catchAll}"
    "Priority": 0
}

{
    "UpstreamPathTemplate": "/goods/delete"
    "Priority": 1
}

在上面的例子中，如果你通过/goods/delete请求Ocelot，将匹配到/goods/delete ReRoute。

Query Strings

你可以在DownstreamPathTemplate中使用querystring：

{
    "ReRoutes": [
        {
            "DownstreamPathTemplate": "/api/subscriptions/{subscriptionId}/updates?unitId={unitId}",
            "UpstreamPathTemplate": "/api/units/{subscriptionId}/{unitId}/updates",
            "UpstreamHttpMethod": [
                "Get"
            ],
            "DownstreamScheme": "http",
            "DownstreamHostAndPorts": [
                {
                    "Host": "localhost",
                    "Port": 50110
                }
            ]
        }
    ],
    "GlobalConfiguration": {
        "UseServiceDiscovery": false
    }
}

在上面的例子中，ocelot会将upstream path template中的{unitId}的值，添加到downstream的querystring中去。

同样也可以在UpstreamPathTemplate中使用querystring：

{
    "ReRoutes": [
        {
            "DownstreamPathTemplate": "/api/units/{subscriptionId}/{unitId}/updates",
            "UpstreamPathTemplate": "/api/subscriptions/{subscriptionId}/updates?unitId={unitId}",
            "UpstreamHttpMethod": [
                "Get"
            ],
            "DownstreamScheme": "http",
            "DownstreamHostAndPorts": [
                {
                    "Host": "localhost",
                    "Port": 50110
                }
            ]
        }
    ],
    "GlobalConfiguration": {
        "UseServiceDiscovery": false
    }
}

上面的例子中Ocelot会将上游模板querystring中的{unitid}作为下游的url path中的一部分。