APIs e scripts

Nos seus scripts Studio, é possível se conectar a serviços web que usam padrões API SOAP ou RESTful.

Opções suportadas

O Studio suporta as seguintes maneiras de conexão a serviços web:

Opção	Detalhes
Ação Studio REST API	A ação REST API do Studio permite que você faça chamadas API RESTful a partir dos seus scripts. Este método: Pode lidar com cargas mais altas em comparação com chamadas API RESTful feitas com uma ação SNIPPET, particularmente em escala. É o método preferencial para se fazer chamadas API em scripts. É a opção para uso se suas chamadas incluírem JSON.
Ações de API CXoneStudio	O Studio possui várias ações de API que permitem que você faça chamadas para APIs CXone a partir dos seus scripts. Nem toda API CXone está disponível como uma ação, mas quando uma está disponível, você deve usá-la em vez de outro método. Você pode encontrar as ações de API na seção API na guia Estrutura no Desktop Studio e na paleta de Ações de API no CXone Studio.
Ações SNIPPET	Você pode escrever código em uma ação SNIPPET para se conectar com serviços web RESTful ou SOAP a partir do seu script. Este não é o método recomendado para se fazer chamadas REST porque pode retardar o atendimento de contatos. No entanto, você deve usar este método se: Suas chamadas incluírem XML. Estiver se conectando a um serviço SOAP.

Opção

Detalhes

Ação Studio REST API

A ação REST API do Studio permite que você faça chamadas API RESTful a partir dos seus scripts. Este método:

Pode lidar com cargas mais altas em comparação com chamadas API RESTful feitas com uma ação SNIPPET, particularmente em escala.
É o método preferencial para se fazer chamadas API em scripts.
É a opção para uso se suas chamadas incluírem JSON.

Ações de API CXoneStudio

O Studio possui várias ações de API que permitem que você faça chamadas para APIs CXone a partir dos seus scripts. Nem toda API CXone está disponível como uma ação, mas quando uma está disponível, você deve usá-la em vez de outro método. Você pode encontrar as ações de API na seção API na guia Estrutura no Desktop Studio e na paleta de Ações de API no CXone Studio.

Ações SNIPPET

Você pode escrever código em uma ação SNIPPET para se conectar com serviços web RESTful ou SOAP a partir do seu script. Este não é o método recomendado para se fazer chamadas REST porque pode retardar o atendimento de contatos. No entanto, você deve usar este método se:

Suas chamadas incluírem XML.
Estiver se conectando a um serviço SOAP.

Limitações no tamanho de dados retornados

O CXone plataforma permite que as APIs REST retornem até 32 KB de dados. Esse limite evita instabilidade e interrupções do cluster. Isto é rigorosamente aplicado.

Este limite é aplicado a qualquer método de conexão com serviços web, incluindo a ação REST API e chamadas feitas com a ação SNIPPET. Se possível, use a ação REST API em vez da ação SNIPPET para suas APIs REST. A REST API tem um limite de retorno de 32 KB, mas pode lidar com uma carga mais pesada que o método SNIPPET.

Para reduzir o tamanho dos dados retornados:

Filtre os dados na resposta da API. Por exemplo, se estiver usando a API de relatórios NICE para obter contatos, você pode filtrar os resultados pela startDate e endDate do contato. Esta chamada de API também permite retornar e limitar uma contagem máxima de itens. Consulte a documentação para que a API que está chamando determine qual filtro você pode usar.
Atualize a solicitação da API para retornar apenas os dados de que precisa. Por exemplo, se estiver usando a API de relatórios NICE para obter contatos, você pode usar os campos contactId ou agentId para retornar apenas dados relevantes. Consulte a documentação para que a API que está chamando determine quais limites de dados você pode usar.

Se você não puder fazer nenhuma das opções anteriores, crie um middleware.

Código de erro -1

O código de erro -1 é um código interno usado para identificar que um erro foi encontrado com uma chamada de API. Mais especificamente, este código indica que esta é uma situação onde um código de status HTTP não será retornado ou onde o código é retornado mas não pode ser passado ao script.

A descrição de status que acompanha o código de erro -1 pode ajudá-lo(a) a determinar o problema. As descrições de status que podem acompanhar este código são:

A solicitação foi abortada: tempo limite da operação esgotado. A solicitação pode ou não ter sido processada. Validação deve ocorrer antes da definição de um loop em resposta a um código de status -1. Pode ser necessário alterar a configuração de tempo limite na chamada usando a propriedade ProxyTimeoutSeconds.
Primitivo JSON inválido. O analisador de JSON ficou confuso com a resposta. A resposta pode ter incluído caracteres inválidos ou não estava em JSON. Com frequência, este erro ocorre quando a resposta é enviada em HTML. Você pode testar a resposta no depurador snippet. O artigo da base de conhecimento Resposta API REST não é JSON ou XML válido pode ajudá-lo(a).
Dados na raiz são inválidos. O analisador de XML ficou confuso com a resposta. A resposta pode ter incluído caracteres inválidos ou não estava em XML. Com frequência, este erro ocorre quando a resposta é enviada em HTML. O artigo da base de conhecimento Resposta API REST não é JSON ou XML válido pode ajudá-lo(a).
'doctype’ é um token inesperado. O token esperado é 'DOCTYPE'. Consulte Dados na raiz são inválidos nesta lista.
A tag inicial 'br’ na linha x posição x não corresponde à tag final de 'corpo'. Consulte Dados na raiz são inválidos nesta lista.
A conexão subjacente foi encerrada: ocorreu um erro inesperado em um envio. Frequentemente, isso significa que há um problema com o handshake TLS. Ele também pode ser causado por um IP ou uma porta não sendo abertos em um firewall; pelo uso de uma versão velha e não suportada de TLS; por certificados inválidos ou vencidos; pelo uso de um endereço IP em conjunto com HTTPS; ou problemas parecidos. Solucione o problema desta resposta com os registros de firewall do servidor de recepção.
A conexão subjacente foi encerrada: não foi possível estabelecer uma relação de confiança para o canal seguro SSL/TLS. Consulte A conexão subjacente foi encerrada: ocorreu um erro inesperado em um envio nesta lista.
A solicitação foi abortada: não foi possível criar um canal seguro SSL/TLS. Consulte A conexão subjacente foi encerrada: ocorreu um erro inesperado em um envio nesta lista.
Resposta grande demais. (> 32 KB). A resposta contém mais de 32 KB de dados. Quando isto ocorre, a resposta é descartada pois o sistema não tem como armazenar mais de 32 KB em uma variável. A resposta deve ser alterada ou filtrada para reduzir a quantidade de dados retornados.