Common parameters of the AI Guardrails API - AI Guardrails: Central de Documentação do Alibaba Cloud

Cabeçalhos de requisição comuns

Escolha um método de assinatura

A API do AI Guardrails oferece suporte a dois métodos de assinatura. A escolha determina quais cabeçalhos são obrigatórios:

Método de assinatura	Content-MD5	x-acs-content-sm3
HMAC-SHA1 (padrão)	Obrigatório	Não utilizado
HMAC-SM3	Opcional	Obrigatório

Para obter detalhes sobre como gerar assinaturas, consulte Assinaturas de requisição.

Referência de cabeçalhos

Cabeçalho	Tipo	Obrigatório	Descrição
`Accept`	String	Sim	Formato de resposta aceito. Defina como `application/json`.
`Content-Type`	String	Sim	Formato do corpo da requisição. Defina como `application/json`.
`Content-MD5`	String	Condicional	Hash MD5 do corpo da requisição codificado em Base64. Calcule assim: MD5(string do corpo da requisição) → binário → codificação Base64. Obrigatório ao usar HMAC-SHA1. Opcional ao usar HMAC-SM3.
`Date`	String	Sim	Timestamp da requisição no formato GMT. Exemplo: `Tue, 17 Jan 2017 10:16:36 GMT`.
`x-acs-version`	String	Sim	Versão da API. Defina como `2018-05-09`.
`x-acs-signature-nonce`	String	Sim	String aleatória única para evitar ataques de replay. Use um valor diferente para cada requisição.
`x-acs-signature-version`	String	Sim	Versão do algoritmo de assinatura. Defina como `1.0`.
`x-acs-signature-method`	String	Sim	Método de assinatura. Valores válidos: `HMAC-SHA1` (padrão), `HMAC-SM3`.
`x-acs-content-sm3`	String	Condicional	Hash SM3 do corpo da requisição codificado como string hexadecimal. Calcule assim: `encodeHexString(SM3Digest(body))`. Obrigatório ao usar HMAC-SM3.
`Authorization`	String	Sim	Credencial de autenticação. Formato: `acs <AccessKeyId>:<signature>`. Obtenha seu AccessKey ID no Console de Gerenciamento da Alibaba Cloud. Para obter detalhes sobre como gerar a assinatura, consulte Assinaturas de requisição.

Importante

Versões anteriores a 2018-05-09 foram descontinuadas. Requisições que usam uma versão mais antiga retornam HttpCode:400, ErrorCode:InvalidAction.NotFound. Atualize suas requisições para usar a versão 2018-05-09.

Parâmetros de requisição comuns

Inclua os parâmetros de requisição comuns na query string das requisições HTTP POST.

Parâmetro	Tipo	Obrigatório	Descrição
`clientInfo`	String	Não	Metadados do cliente serializados a partir da estrutura `ClientInfo` no formato JSON. Inclui identificadores de dispositivo, como UMID (identificador único de máquina) e IMEI (Identidade Internacional de Equipamento Móvel). Consulte Parâmetros de ClientInfo.

Parâmetros de ClientInfo

O valor de clientInfo é um objeto ClientInfo serializado em JSON. Passe-o como um parâmetro de consulta codificado por URL.

Parâmetro	Tipo	Obrigatório	Descrição
`sdkVersion`	String	Condicional	Versão do SDK do AI Guardrails. Obrigatório ao chamar a API pelo SDK do AI Guardrails.
`cfgVersion`	String	Condicional	Versão da configuração. Obrigatório ao chamar a API pelo SDK do AI Guardrails.
`userType`	String	Não	Tipo de conta de usuário. Valores válidos: `taobao` (conta Taobao), `others` (todos os outros tipos de conta).
`userId`	String	Não	ID exclusivo do usuário no seu sistema empresarial. Definir este parâmetro ajuda a detectar possíveis violações de política cometidas por um usuário específico.
`userNick`	String	Não	Apelido do usuário.
`imei`	String	Não	IMEI (Identidade Internacional de Equipamento Móvel) do dispositivo.
`imsi`	String	Não	IMSI (Identidade Internacional de Assinante Móvel) do dispositivo.
`umid`	String	Não	UMID (identificador único de máquina) do dispositivo.
`ip`	String	Não	Endereço IP público do usuário. Deixe em branco se a requisição for originada diretamente do dispositivo. Se a requisição partir de um servidor, defina este campo com o endereço IP de login do usuário ou o endereço IP público do dispositivo. Se omitido, o servidor tentará obter o endereço IP a partir da URL da requisição ou dos cabeçalhos HTTP. Recomendamos definir este parâmetro para facilitar a análise do comportamento de violação do usuário.
`os`	String	Não	Sistema operacional do dispositivo. Exemplo: `Android 6.0`.
`channel`	String	Não	Número do canal.
`hostAppName`	String	Não	Nome do aplicativo hospedeiro.
`hostPackage`	String	Não	Nome do pacote do aplicativo hospedeiro.
`hostVersion`	String	Não	Versão do aplicativo hospedeiro.

Exemplo de requisição

O exemplo a seguir apresenta uma requisição HTTP POST completa que verifica violações de política em uma imagem.

POST /green/image/scan?clientInfo=%7b%22userId%22%3a%22120234234%22%2c%22userNick%22%3a%22Mike%22%2c%22userType%22%3a%22others%22%7d HTTP/1.1
Host: green.cn-shanghai.aliyuncs.com/
Accept: application/json
Content-Type: application/json
Content-MD5: C+5Y0crpO4sYgC2DNjycug==
Date: Tue, 15 May 2018 10:16:36 GMT
x-acs-version: 2018-05-09
x-acs-signature-nonce: adfkjfaHKslkjf
x-acs-signature-version: 1.0
x-acs-signature-method: HMAC-SHA1
Authorization: acs q23Q9K4PaGi12Wyk:adFff0FFO6sGcDbDNjRtso==
Content-Length: 191

{
    "scenes": [
        "porn"
    ],
    "tasks": [
        {
            "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
            "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

Principais componentes desta requisição:

Caminho da requisição: /green/image/scan — operação da API para verificação de imagens.
Query string: O valor clientInfo codificado por URL transmite o contexto do usuário (userId, userNick, userType) junto com o caminho.
Cabeçalhos comuns: Os cabeçalhos de Accept até Authorization constituem os cabeçalhos de requisição comuns obrigatórios, utilizados para autenticar e assinar a requisição.
Corpo da requisição: O corpo JSON define scenes (cenário de moderação) e tasks (conteúdo a ser verificado). A estrutura varia conforme a operação da API. Para obter a lista completa de operações, consulte Lista de operações por função.

Próximos passos

Assinaturas de requisição — Aprenda a gerar o valor do cabeçalho Authorization.
Obter um par de AccessKey — Adquira as credenciais necessárias para autenticar requisições.
Visão geral do SDK — Use o SDK do AI Guardrails para chamar a API sem precisar construir requisições manualmente.
Lista de operações por função — Explore todas as operações de API disponíveis.