mirror of
https://github.com/nsnail/Ocelot.git
synced 2025-04-22 18:22:49 +08:00
Add syntax highlighting to readme.md
This commit is contained in:
parent
9203e7f465
commit
0b4aee7b96
39
README.md
39
README.md
@ -61,11 +61,12 @@ The ReRoutes are the objects that tell Ocelot how to treat an upstream request.
|
|||||||
configuration is a bit hacky and allows overrides of ReRoute specific settings. It's useful
|
configuration is a bit hacky and allows overrides of ReRoute specific settings. It's useful
|
||||||
if you don't want to manage lots of ReRoute specific settings.
|
if you don't want to manage lots of ReRoute specific settings.
|
||||||
|
|
||||||
|
```json
|
||||||
{
|
{
|
||||||
"ReRoutes": [],
|
"ReRoutes": [],
|
||||||
"GlobalConfiguration": {}
|
"GlobalConfiguration": {}
|
||||||
}
|
}
|
||||||
|
```
|
||||||
More information on how to use these options is below..
|
More information on how to use these options is below..
|
||||||
|
|
||||||
## Startup
|
## Startup
|
||||||
@ -73,6 +74,7 @@ More information on how to use these options is below..
|
|||||||
An example startup using a json file for configuration can be seen below.
|
An example startup using a json file for configuration can be seen below.
|
||||||
Currently this is the only way to get configuration into Ocelot.
|
Currently this is the only way to get configuration into Ocelot.
|
||||||
|
|
||||||
|
```csharp
|
||||||
public class Startup
|
public class Startup
|
||||||
{
|
{
|
||||||
public Startup(IHostingEnvironment env)
|
public Startup(IHostingEnvironment env)
|
||||||
@ -112,7 +114,7 @@ Currently this is the only way to get configuration into Ocelot.
|
|||||||
app.UseOcelot();
|
app.UseOcelot();
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
This is pretty much all you need to get going.......more to come!
|
This is pretty much all you need to get going.......more to come!
|
||||||
|
|
||||||
@ -127,14 +129,17 @@ Ocelot always adds a trailing slash to an UpstreamPathTemplate.
|
|||||||
Ocelot's describes the routing of one request to another as a ReRoute. In order to get
|
Ocelot's describes the routing of one request to another as a ReRoute. In order to get
|
||||||
anything working in Ocelot you need to set up a ReRoute in the configuration.
|
anything working in Ocelot you need to set up a ReRoute in the configuration.
|
||||||
|
|
||||||
|
```json
|
||||||
{
|
{
|
||||||
"ReRoutes": [
|
"ReRoutes": [
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
In order to set up a ReRoute you need to add one to the json array called ReRoutes like
|
In order to set up a ReRoute you need to add one to the json array called ReRoutes like
|
||||||
the following.
|
the following.
|
||||||
|
|
||||||
|
```json
|
||||||
{
|
{
|
||||||
"DownstreamPathTemplate": "/api/posts/{postId}",
|
"DownstreamPathTemplate": "/api/posts/{postId}",
|
||||||
"DownstreamScheme": "https",
|
"DownstreamScheme": "https",
|
||||||
@ -143,6 +148,7 @@ the following.
|
|||||||
"UpstreamPathTemplate": "/posts/{postId}",
|
"UpstreamPathTemplate": "/posts/{postId}",
|
||||||
"UpstreamHttpMethod": "Put"
|
"UpstreamHttpMethod": "Put"
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
The DownstreamPathTemplate,Scheme, Port and Host make the URL that this request will be forwarded to.
|
The DownstreamPathTemplate,Scheme, Port and Host make the URL that this request will be forwarded to.
|
||||||
The UpstreamPathTemplate is the URL that Ocelot will use to identity which
|
The UpstreamPathTemplate is the URL that Ocelot will use to identity which
|
||||||
@ -156,7 +162,9 @@ Upstream URL when the request comes in.
|
|||||||
At the moment without any configuration Ocelot will default to all ReRoutes being case insensitive.
|
At the moment without any configuration Ocelot will default to all ReRoutes being case insensitive.
|
||||||
In order to change this you can specify on a per ReRoute basis the following setting.
|
In order to change this you can specify on a per ReRoute basis the following setting.
|
||||||
|
|
||||||
|
```json
|
||||||
"ReRouteIsCaseSensitive": true
|
"ReRouteIsCaseSensitive": true
|
||||||
|
```
|
||||||
|
|
||||||
This means that when Ocelot tries to match the incoming upstream url with an upstream template the
|
This means that when Ocelot tries to match the incoming upstream url with an upstream template the
|
||||||
evaluation will be case sensitive. This setting defaults to false so only set it if you want
|
evaluation will be case sensitive. This setting defaults to false so only set it if you want
|
||||||
@ -176,17 +184,19 @@ At the moment the only supported service discovery provider is Consul. The follo
|
|||||||
GlobalConfiguration. The Provider is required and if you do not specify a host and port the Consul default
|
GlobalConfiguration. The Provider is required and if you do not specify a host and port the Consul default
|
||||||
will be used.
|
will be used.
|
||||||
|
|
||||||
"ServiceDiscoveryProvider":
|
```json
|
||||||
{
|
"ServiceDiscoveryProvider": {
|
||||||
"Provider":"Consul",
|
"Provider":"Consul",
|
||||||
"Host":"localhost",
|
"Host":"localhost",
|
||||||
"Port":8500
|
"Port":8500
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
In order to tell Ocelot a ReRoute is to use the service discovery provider for its host and port you must add the
|
In order to tell Ocelot a ReRoute is to use the service discovery provider for its host and port you must add the
|
||||||
ServiceName and load balancer you wish to use when making requests downstream. At the moment Ocelot has a RoundRobin
|
ServiceName and load balancer you wish to use when making requests downstream. At the moment Ocelot has a RoundRobin
|
||||||
and LeastConnection algorithm you can use. If no load balancer is specified Ocelot will not load balance requests.
|
and LeastConnection algorithm you can use. If no load balancer is specified Ocelot will not load balance requests.
|
||||||
|
|
||||||
|
```json
|
||||||
{
|
{
|
||||||
"DownstreamPathTemplate": "/api/posts/{postId}",
|
"DownstreamPathTemplate": "/api/posts/{postId}",
|
||||||
"DownstreamScheme": "https",
|
"DownstreamScheme": "https",
|
||||||
@ -195,6 +205,7 @@ and LeastConnection algorithm you can use. If no load balancer is specified Ocel
|
|||||||
"ServiceName": "product"
|
"ServiceName": "product"
|
||||||
"LoadBalancer": "LeastConnection"
|
"LoadBalancer": "LeastConnection"
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
When this is set up Ocelot will lookup the downstream host and port from the service discover provider and load balancer
|
When this is set up Ocelot will lookup the downstream host and port from the service discover provider and load balancer
|
||||||
requests across any available services.
|
requests across any available services.
|
||||||
@ -206,6 +217,7 @@ Ocelot currently supports the use of bearer tokens with Identity Server (more pr
|
|||||||
come if required). In order to identity a ReRoute as authenticated it needs the following
|
come if required). In order to identity a ReRoute as authenticated it needs the following
|
||||||
configuration added.
|
configuration added.
|
||||||
|
|
||||||
|
```json
|
||||||
"AuthenticationOptions": {
|
"AuthenticationOptions": {
|
||||||
"Provider": "IdentityServer",
|
"Provider": "IdentityServer",
|
||||||
"ProviderRootUrl": "http://localhost:52888",
|
"ProviderRootUrl": "http://localhost:52888",
|
||||||
@ -216,6 +228,7 @@ configuration added.
|
|||||||
],
|
],
|
||||||
"ScopeSecret": "secret"
|
"ScopeSecret": "secret"
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
In this example the Provider is specified as IdentityServer. This string is important
|
In this example the Provider is specified as IdentityServer. This string is important
|
||||||
because it is used to identity the authentication provider (as previously mentioned in
|
because it is used to identity the authentication provider (as previously mentioned in
|
||||||
@ -234,9 +247,11 @@ is 401 unauthorised.
|
|||||||
Ocelot supports claims based authorisation which is run post authentication. This means if
|
Ocelot supports claims based authorisation which is run post authentication. This means if
|
||||||
you have a route you want to authorise you can add the following to you ReRoute configuration.
|
you have a route you want to authorise you can add the following to you ReRoute configuration.
|
||||||
|
|
||||||
|
```json
|
||||||
"RouteClaimsRequirement": {
|
"RouteClaimsRequirement": {
|
||||||
"UserType": "registered"
|
"UserType": "registered"
|
||||||
},
|
},
|
||||||
|
```
|
||||||
|
|
||||||
In this example when the authorisation middleware is called Ocelot will check to see
|
In this example when the authorisation middleware is called Ocelot will check to see
|
||||||
if the user has the claim type UserType and if the value of that claim is registered.
|
if the user has the claim type UserType and if the value of that claim is registered.
|
||||||
@ -275,10 +290,12 @@ and add whatever was at the index requested to the transform.
|
|||||||
|
|
||||||
Below is an example configuration that will transforms claims to claims
|
Below is an example configuration that will transforms claims to claims
|
||||||
|
|
||||||
|
```json
|
||||||
"AddClaimsToRequest": {
|
"AddClaimsToRequest": {
|
||||||
"UserType": "Claims[sub] > value[0] > |",
|
"UserType": "Claims[sub] > value[0] > |",
|
||||||
"UserId": "Claims[sub] > value[1] > |"
|
"UserId": "Claims[sub] > value[1] > |"
|
||||||
},
|
},
|
||||||
|
```
|
||||||
|
|
||||||
This shows a transforms where Ocelot looks at the users sub claim and transforms it into
|
This shows a transforms where Ocelot looks at the users sub claim and transforms it into
|
||||||
UserType and UserId claims. Assuming the sub looks like this "usertypevalue|useridvalue".
|
UserType and UserId claims. Assuming the sub looks like this "usertypevalue|useridvalue".
|
||||||
@ -287,9 +304,11 @@ UserType and UserId claims. Assuming the sub looks like this "usertypevalue|user
|
|||||||
|
|
||||||
Below is an example configuration that will transforms claims to headers
|
Below is an example configuration that will transforms claims to headers
|
||||||
|
|
||||||
|
```json
|
||||||
"AddHeadersToRequest": {
|
"AddHeadersToRequest": {
|
||||||
"CustomerId": "Claims[sub] > value[1] > |"
|
"CustomerId": "Claims[sub] > value[1] > |"
|
||||||
},
|
},
|
||||||
|
```
|
||||||
|
|
||||||
This shows a transform where Ocelot looks at the users sub claim and trasnforms it into a
|
This shows a transform where Ocelot looks at the users sub claim and trasnforms it into a
|
||||||
CustomerId header. Assuming the sub looks like this "usertypevalue|useridvalue".
|
CustomerId header. Assuming the sub looks like this "usertypevalue|useridvalue".
|
||||||
@ -298,9 +317,11 @@ CustomerId header. Assuming the sub looks like this "usertypevalue|useridvalue".
|
|||||||
|
|
||||||
Below is an example configuration that will transforms claims to query string parameters
|
Below is an example configuration that will transforms claims to query string parameters
|
||||||
|
|
||||||
|
```json
|
||||||
"AddQueriesToRequest": {
|
"AddQueriesToRequest": {
|
||||||
"LocationId": "Claims[LocationId] > value",
|
"LocationId": "Claims[LocationId] > value",
|
||||||
},
|
},
|
||||||
|
```
|
||||||
|
|
||||||
This shows a transform where Ocelot looks at the users LocationId claim and add its as
|
This shows a transform where Ocelot looks at the users LocationId claim and add its as
|
||||||
a query string parameter to be forwarded onto the downstream service.
|
a query string parameter to be forwarded onto the downstream service.
|
||||||
@ -313,11 +334,13 @@ want to use a circuit breaker when making requests to a downstream service. This
|
|||||||
|
|
||||||
Add the following section to a ReRoute configuration.
|
Add the following section to a ReRoute configuration.
|
||||||
|
|
||||||
|
```json
|
||||||
"QoSOptions": {
|
"QoSOptions": {
|
||||||
"ExceptionsAllowedBeforeBreaking":3,
|
"ExceptionsAllowedBeforeBreaking":3,
|
||||||
"DurationOfBreak":5,
|
"DurationOfBreak":5,
|
||||||
"TimeoutValue":5000
|
"TimeoutValue":5000
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
You must set a number greater than 0 against ExceptionsAllowedBeforeBreaking for this rule to be
|
You must set a number greater than 0 against ExceptionsAllowedBeforeBreaking for this rule to be
|
||||||
implemented. Duration of break is how long the circuit breaker will stay open for after it is tripped.
|
implemented. Duration of break is how long the circuit breaker will stay open for after it is tripped.
|
||||||
@ -338,14 +361,18 @@ have an OcelotRequestId.
|
|||||||
|
|
||||||
In order to use the requestid feature in your ReRoute configuration add this setting
|
In order to use the requestid feature in your ReRoute configuration add this setting
|
||||||
|
|
||||||
|
```json
|
||||||
"RequestIdKey": "OcRequestId"
|
"RequestIdKey": "OcRequestId"
|
||||||
|
```
|
||||||
|
|
||||||
In this example OcRequestId is the request header that contains the clients request id.
|
In this example OcRequestId is the request header that contains the clients request id.
|
||||||
|
|
||||||
There is also a setting in the GlobalConfiguration section which will override whatever has been
|
There is also a setting in the GlobalConfiguration section which will override whatever has been
|
||||||
set at ReRoute level for the request id. The setting is as fllows.
|
set at ReRoute level for the request id. The setting is as fllows.
|
||||||
|
|
||||||
|
```json
|
||||||
"RequestIdKey": "OcRequestId",
|
"RequestIdKey": "OcRequestId",
|
||||||
|
```
|
||||||
|
|
||||||
It behaves in exactly the same way as the ReRoute level RequestIdKey settings.
|
It behaves in exactly the same way as the ReRoute level RequestIdKey settings.
|
||||||
|
|
||||||
@ -364,7 +391,9 @@ and setting a TTL in seconds to expire the cache. More to come!
|
|||||||
|
|
||||||
In orde to use caching on a route in your ReRoute configuration add this setting.
|
In orde to use caching on a route in your ReRoute configuration add this setting.
|
||||||
|
|
||||||
|
```json
|
||||||
"FileCacheOptions": { "TtlSeconds": 15 }
|
"FileCacheOptions": { "TtlSeconds": 15 }
|
||||||
|
```
|
||||||
|
|
||||||
In this example ttl seconds is set to 15 which means the cache will expire after 15 seconds.
|
In this example ttl seconds is set to 15 which means the cache will expire after 15 seconds.
|
||||||
|
|
||||||
@ -376,6 +405,7 @@ pipeline and you are using any of the following. Remove them and try again!
|
|||||||
When setting up Ocelot in your Startup.cs you can provide some additonal middleware
|
When setting up Ocelot in your Startup.cs you can provide some additonal middleware
|
||||||
and override middleware. This is done as follos.
|
and override middleware. This is done as follos.
|
||||||
|
|
||||||
|
```csharp
|
||||||
var configuration = new OcelotMiddlewareConfiguration
|
var configuration = new OcelotMiddlewareConfiguration
|
||||||
{
|
{
|
||||||
PreErrorResponderMiddleware = async (ctx, next) =>
|
PreErrorResponderMiddleware = async (ctx, next) =>
|
||||||
@ -385,6 +415,7 @@ and override middleware. This is done as follos.
|
|||||||
};
|
};
|
||||||
|
|
||||||
app.UseOcelot(configuration);
|
app.UseOcelot(configuration);
|
||||||
|
```
|
||||||
|
|
||||||
In the example above the provided function will run before the first piece of Ocelot middleware.
|
In the example above the provided function will run before the first piece of Ocelot middleware.
|
||||||
This allows a user to supply any behaviours they want before and after the Ocelot pipeline has run.
|
This allows a user to supply any behaviours they want before and after the Ocelot pipeline has run.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user