Expressões da política de Gerenciamento de API

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

Este artigo discute a sintaxe de expressões de política em C# 7. Cada expressão tem acesso a:

Sintaxe

  • Expressões de declaração única:
    • Incluído em @(expression), onde expression está uma instrução de expressão C# bem formada.
  • Expressões com várias instruções:
    • Incluído em @{expression}.
    • Todos os caminhos de código dentro de expressões de várias instruções devem terminar com uma return instrução.

Exemplos

@(true)

@((1+1).ToString())

@("Hi There".Length)

@(Regex.Match(context.Response.Headers.GetValueOrDefault("Cache-Control",""), @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value)

@(context.Variables.ContainsKey("maxAge") ? int.Parse((string)context.Variables["maxAge"]) : 3600)

@{
  string[] value;
  if (context.Request.Headers.TryGetValue("Authorization", out value))
  {
      if(value != null && value.Length > 0)
      {
          return Encoding.UTF8.GetString(Convert.FromBase64String(value[0]));
      }
  }
  return null;

}

Utilização

A menos que a referência de política especifique o contrário, as expressões podem ser usadas como valores de atributo ou valores de texto em qualquer política de Gerenciamento de API.

Importante

Quando a política é definida, as expressões têm apenas uma verificação limitada. As expressões são executadas pelo gateway em tempo de execução. Quaisquer exceções geradas por expressões de políticas resultam num erro de runtime.

Tipos do .NET Framework permitidos em expressões de política

A tabela a seguir lista os tipos e membros do .NET Framework permitidos em expressões de política.

Type Membros suportados
Newtonsoft.Json.Formatting Todos
Newtonsoft.Json.JsonConvert SerializeObject, DeserializeObject
Newtonsoft.Json.Linq.Extensions Todos
Newtonsoft.Json.Linq.JArray Todos
Newtonsoft.Json.Linq.JConstructor Todos
Newtonsoft.Json.Linq.JContainer Todos
Newtonsoft.Json.Linq.JObject Todos
Newtonsoft.Json.Linq.JProperty Todos
Newtonsoft.Json.Linq.JRaw Todos
Newtonsoft.Json.Linq.JToken Todos
Newtonsoft.Json.Linq.JTokenType Todos
Newtonsoft.Json.Linq.JValue Todos
System.Array Todos
System.BitConverter Todos
System.Boolean Todos
System.Byte Todos
System.Char Todos
System.Collections.Generic.Dictionary<TKey, TValue> Todos
System.Collections.Generic.HashSet<T> Todos
System.Collections.Generic.ICollection<T> Todos
System.Collections.Generic.IDictionary<TKey, TValue> Todos
System.Collections.Generic.IEnumerable<T> Todos
System.Collections.Generic.IEnumerator<T> Todos
System.Collections.Generic.IList<T> Todos
System.Collections.Generic.IReadOnlyCollection<T> Todos
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue> Todos
System.Collections.Generic.ISet<T> Todos
System.Collections.Generic.KeyValuePair<TKey, TValue> Todos
System.Collections.Generic.List<T> Todos
System.Collections.Generic.Queue<T> Todos
System.Collections.Generic.Stack<T> Todos
System.Convert Todos
System.DateTime (Construtor), , , , , NowIsDaylightSavingTimeHourIsLeapYearDaysInMonthDayOfYearDayOfWeekMaxValueDayDateAddYearsMillisecondAddTicksAddSecondsAddMonthsAddMinutesToStringParseSecondSubtractMonthTimeOfDayUtcNowTicksMinuteMinValueTodayAddMillisecondsAddHoursAddDaysAddYear
System.DateTimeKind Utc
System.DateTimeOffset Todos
System.Decimal Todos
System.Double Todos
System.Enum Parse, TryParse, ToString
System.Exception Todos
System.Guid Todos
System.Int16 Todos
System.Int32 Todos
System.Int64 Todos
System.IO.StringReader Todos
System.IO.StringWriter Todos
System.Linq.Enumerable Todos
System.Math Todos
System.MidpointRounding Todos
System.Net.IPAddress AddressFamily, Equals, GetAddressBytes, IsLoopback, Parse, TryParse, ToString
System.Net.WebUtility Todos
System.Nullable Todos
System.Random Todos
System.SByte Todos
System.Security.Cryptography.AsymmetricAlgorithm Todos
System.Security.Cryptography.CipherMode Todos
System.Security.Cryptography.HashAlgorithm Todos
System.Security.Cryptography.HashAlgorithmName Todos
System.Security.Cryptography.HMAC Todos
System.Security.Cryptography.HMACMD5 Todos
System.Security.Cryptography.HMACSHA1 Todos
System.Security.Cryptography.HMACSHA256 Todos
System.Security.Cryptography.HMACSHA384 Todos
System.Security.Cryptography.HMACSHA512 Todos
System.Security.Cryptography.KeyedHashAlgorithm Todos
System.Security.Cryptography.MD5 Todos
System.Security.Cryptography.Oid Todos
System.Security.Cryptography.PaddingMode Todos
System.Security.Cryptography.RNGCryptoServiceProvider Todos
System.Security.Cryptography.RSA Todos
System.Security.Cryptography.RSAEncryptionPadding Todos
System.Security.Cryptography.RSASignaturePadding Todos
System.Security.Cryptography.SHA1 Todos
System.Security.Cryptography.SHA1Managed Todos
System.Security.Cryptography.SHA256 Todos
System.Security.Cryptography.SHA256Managed Todos
System.Security.Cryptography.SHA384 Todos
System.Security.Cryptography.SHA384Managed Todos
System.Security.Cryptography.SHA512 Todos
System.Security.Cryptography.SHA512Managed Todos
System.Security.Cryptography.SymmetricAlgorithm Todos
System.Security.Cryptography.X509Certificates.PublicKey Todos
System.Security.Cryptography.X509Certificates.RSACertificateExtensions Todos
System.Security.Cryptography.X509Certificates.X500DistinguishedName Name
System.Security.Cryptography.X509Certificates.X509Certificate Todos
System.Security.Cryptography.X509Certificates.X509Certificate2 Todos
System.Security.Cryptography.X509Certificates.X509ContentType Todos
System.Security.Cryptography.X509Certificates.X509NameType Todos
System.Single Todos
System.String Todos
System.StringComparer Todos
System.StringComparison Todos
System.StringSplitOptions Todos
System.Text.Encoding Todos
System.Text.RegularExpressions.Capture Index, Length, Value
System.Text.RegularExpressions.CaptureCollection Count, Item
System.Text.RegularExpressions.Group Captures, Success
System.Text.RegularExpressions.GroupCollection Count, Item
System.Text.RegularExpressions.Match Empty, Groups, Result
System.Text.RegularExpressions.Regex (Construtor), IsMatch, Match, Matches, Replace, Unescape, , Split
System.Text.RegularExpressions.RegexOptions Todos
System.Text.StringBuilder Todos
System.TimeSpan Todos
System.TimeZone Todos
System.TimeZoneInfo.AdjustmentRule Todos
System.TimeZoneInfo.TransitionTime Todos
System.TimeZoneInfo Todos
System.Tuple Todos
System.UInt16 Todos
System.UInt32 Todos
System.UInt64 Todos
System.Uri Todos
System.UriPartial Todos
System.Xml.Linq.Extensions Todos
System.Xml.Linq.XAttribute Todos
System.Xml.Linq.XCData Todos
System.Xml.Linq.XComment Todos
System.Xml.Linq.XContainer Todos
System.Xml.Linq.XDeclaration Todos
System.Xml.Linq.XDocument Todos, exceto Load
System.Xml.Linq.XDocumentType Todos
System.Xml.Linq.XElement Todos
System.Xml.Linq.XName Todos
System.Xml.Linq.XNamespace Todos
System.Xml.Linq.XNode Todos
System.Xml.Linq.XNodeDocumentOrderComparer Todos
System.Xml.Linq.XNodeEqualityComparer Todos
System.Xml.Linq.XObject Todos
System.Xml.Linq.XProcessingInstruction Todos
System.Xml.Linq.XText Todos
System.Xml.XmlNodeType Todos

Variável de contexto

A context variável está implicitamente disponível em todas as expressões políticas. Os seus membros:

  • Forneça informações relevantes para a solicitação e resposta da API e propriedades relacionadas.
  • São todos somente leitura.
Variável de contexto Métodos, propriedades e valores de parâmetros permitidos
context Api: IApi

Deployment

Decorrido: TimeSpan - intervalo de tempo entre o valor de Timestamp e o tempo atual

GraphQL

LastError

Operation

Request

RequestId: Guid - identificador único do pedido

Response

Subscription

Timestamp: DateTime - momento em que o pedido foi recebido

Tracing: bool - indica se o rastreio está ativado ou desativado

Utilizador

Variables: IReadOnlyDictionary<string, object>

void Trace(message: string)

Workspace
context.Api Id: string

IsCurrentRevision: bool

Name: string

Path: string

Revision: string

ServiceUrl: IUrl

Version: string
context.Deployment Gateway

GatewayId: string (retorna 'gerenciado' para gateways gerenciados)

Region: string

ServiceId: string

ServiceName: string

Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.Deployment.Gateway Id: string (retorna 'gerenciado' para gateways gerenciados)

InstanceId: string (retorna 'gerenciado' para gateways gerenciados)

IsManaged: bool
context.GraphQL GraphQLArguments: IGraphQLDataObject

Parent: IGraphQLDataObject

Exemplos
context.LastError Source: string

Reason: string

Message: string

Scope: string

Section: string

Path: string

PolicyId: string

Para obter mais informações sobre context.LastErroro , consulte Tratamento de erros.
context.Operation Id: string

Method: string

Name: string

UrlTemplate: string
context.Product ApprovalRequired: bool

Groups: IEnumerable<IGroup>

Id: string

Name: string

State: enum ProductState {NotPublished, Published}

SubscriptionsLimit: int?

SubscriptionRequired: bool
context.Request Body: IMessageBody ou null se o pedido não tiver um corpo.

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary<string, string[]>

IpAddress: string

MatchedParameters: IReadOnlyDictionary<string, string>

Method: string

OriginalUrl: IUrl

Url: IUrl

PrivateEndpointConnection: IPrivateEndpointConnection ou null se a solicitação não vier de uma conexão de ponto de extremidade privada.
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Retorna valores de cabeçalho de solicitação separados por vírgulas ou defaultValue se o cabeçalho não for encontrado.
context.Response Body: IMessageBody

Headers: IReadOnlyDictionary<string, string[]>

StatusCode: int

StatusReason: string
string context.Response.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Retorna valores de cabeçalho de resposta separados por vírgulas ou defaultValue se o cabeçalho não for encontrado.
context.Subscription CreatedDate: DateTime

EndDate: DateTime?

Id: string

Key: string

Name: string

PrimaryKey: string

SecondaryKey: string

StartDate: DateTime?
context.User Email: string

FirstName: string

Groups: IEnumerable<IGroup>

Id: string

Identities: IEnumerable<IUserIdentity>

LastName: string

Note: string

RegistrationDate: DateTime
context.Workspace Id: string

Name: string
IApi Id: string

Name: string

Path: string

Protocols: IEnumerable<string>

ServiceUrl: IUrl

SubscriptionKeyParameterNames: ISubscriptionKeyParameterNames
IGraphQLDataObject TBD
IGroup Id: string

Name: string
IMessageBody As<T>(bool preserveContent = false): Where T: string, byte[], JObject, JToken, JArray, XNode, XElement, XDocument

- Os context.Request.Body.As<T> métodos e context.Response.Body.As<T> lêem um corpo de mensagem de solicitação ou resposta no tipo Tespecificado.

- Ou -

AsFormUrlEncodedContent(bool preserveContent = false)

- Os context.Request.Body.AsFormUrlEncodedContent() métodos e context.Response.Body.AsFormUrlEncodedContent() lêem dados de formulário codificados por URL em um corpo de mensagem de solicitação ou resposta e retornam um IDictionary<string, IList<string> objeto. O objeto decodificado suporta IDictionary operações e as seguintes expressões: ToQueryString(), JsonConvert.SerializeObject(), ToFormUrlEncodedContent().

Por padrão, os As<T> métodos e AsFormUrlEncodedContent() :
  • Use o fluxo do corpo da mensagem original.
  • Torná-lo indisponível depois que ele retornar.

Para evitar isso e fazer com que o método opere em uma cópia do fluxo de corpo, defina o preserveContent parâmetro como true, como mostrado em exemplos para a política set-body .
IPrivateEndpointConnection Name: string

GroupId: string

MemberName: string

Para obter mais informações, consulte a API REST.
IUrl Host: string

Path: string

Port: int

Query: IReadOnlyDictionary<string, string[]>

QueryString: string

Scheme: string
ISubscriptionKeyParameterNames Header: string

Query: string
string IUrl.Query.GetValueOrDefault(queryParameterName: string, defaultValue: string) queryParameterName: string

defaultValue: string

Retorna valores de parâmetros de consulta separados por vírgulas ou defaultValue se o parâmetro não for encontrado.
IUserIdentity Id: string

Provider: string
T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T) variableName: string

defaultValue: T

Retorna o valor da variável convertido para digitar T ou defaultValue se a variável não for encontrada.

Esse método lança uma exceção se o tipo especificado não corresponder ao tipo real da variável retornada.
BasicAuthCredentials AsBasic(input: this string) input: string

Se o parâmetro de entrada contiver um valor de cabeçalho de solicitação de autorização HTTP Basic Authentication válido, o método retornará um objeto do tipo BasicAuthCredentials; caso contrário, o método retornará null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials) input: string

result: out BasicAuthCredentials

Se o parâmetro de entrada contiver um valor de autorização HTTP Basic Authentication válido no cabeçalho da solicitação, o método retornará true e o parâmetro result conterá um valor do tipo BasicAuthCredentials, caso contrário, o método retornará false.
BasicAuthCredentials Password: string

UserId: string
Jwt AsJwt(input: this string) input: string

Se o parâmetro input contiver um valor de token JWT válido, o método retornará um objeto do tipo Jwt, caso contrário, o método retornará null.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

Se o parâmetro input contiver um valor de token JWT válido, o método retornará true e o parâmetro result conterá um valor do tipo Jwt, caso contrário, o método retornará false.
Jwt Algorithm: string

Audiences: IEnumerable<string>

Claims: IReadOnlyDictionary<string, string[]>

ExpirationTime: DateTime?

Id: string

Issuer: string

IssuedAt: DateTime?

NotBefore: DateTime?

Subject: string

Type: string
string Jwt.Claims.GetValueOrDefault(claimName: string, defaultValue: string) claimName: string

defaultValue: string

Retorna valores de declaração separados por vírgulas ou defaultValue se o cabeçalho não for encontrado.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - texto simples a encriptar

alg - nome de um algoritmo de encriptação simétrica

key - chave de encriptação

iv - vetor de inicialização

Retorna texto sem formatação criptografado.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - texto simples a encriptar

alg - algoritmo de encriptação

Retorna texto sem formatação criptografado.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - texto simples a encriptar

alg - algoritmo de encriptação

key - chave de encriptação

iv - vetor de inicialização

Retorna texto sem formatação criptografado.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - texto cypher a ser desencriptado

alg - nome de um algoritmo de encriptação simétrica

key - chave de encriptação

iv - vetor de inicialização

Devolve texto simples.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - texto cypher a ser desencriptado

alg - algoritmo de encriptação

Devolve texto simples.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - texto cypher a ser desencriptado

alg - algoritmo de encriptação

key - chave de encriptação

iv - vetor de inicialização

Devolve texto simples.
bool VerifyNoRevocation(input: this System.Security.Cryptography.X509Certificates.X509Certificate2) Executa uma validação de cadeia X.509 sem verificar o status de revogação do certificado.

input - objeto do certificado

Retorna true se a validação for bem-sucedida, false se a validação falhar.

Conteúdos relacionados

Para obter mais informações sobre como trabalhar com políticas, consulte:

Para mais informações:

  • Veja como fornecer informações de contexto para seu serviço de back-end. Use o parâmetro set query string e set HTTP header policies para fornecer essas informações.
  • Veja como usar a política Validar JWT para pré-autorizar o acesso a operações com base em declarações de token.
  • Veja como usar um rastreamento do Inspetor de API para detetar como as políticas são avaliadas e os resultados dessas avaliações.
  • Veja como usar expressões com as políticas Obter do cache e Armazenar para cache para configurar o cache de resposta do Gerenciamento de API. Defina uma duração que corresponda ao cache de resposta do serviço de back-end, conforme especificado pela diretiva do Cache-Control serviço com backup.
  • Veja como executar a filtragem de conteúdo. Remova elementos de dados da resposta recebida do back-end usando as políticas Fluxo de controle e Definir corpo .
  • Para baixar as instruções de política, consulte o repositório do GitHub api-management-samples/policies .