Fazer Chamadas de API a partir de uma Ação SNIPPET

Você pode fazer Chamadas de API REST ou SOAP a partir de uma ação SNIPPET. Este é um dos métodos aceitos para fazer Chamadas de API em scripts Studio.

Isso não é o método recomendado para fazer chamadas REST, pois tem o potencial de tornar lento o atendimento de contatos e causar problemas graves de desempenho na plataforma. Use um destes métodos preferenciais em vez disso:

Integration Hub: Esta é a opção mais segura e garante que suas credenciais de cliente não sejam armazenadas em texto simples.

Ação da API REST: Usar a REST API ação é a alternativa recomendada se você não estiver usando Integration Hub.

Entretanto, se você estiver se conectando a um serviço web SOAP ou se suas Chamadas de API incluírem xml, fazer chamadas a partir de SNIPPET é o método que você deve usar. Se você precisar usar SNIPPET, revise as recomendações sobre como fazer essas Chamadas de API com mais segurança.

Além de ver os códigos de status HTTP nas respostas, você pode ver um código -1. Este é um código interno que indica a ocorrência de um erro com a resposta.

Cuidado

Não é recomendável criar Chamadas de API dentro de um Snippet. Isso pode causar problemas graves de desempenho que afetam o atendimento de contatos e impactam negativamente seu locatário. Para uma experiência mais segura e confiável, use um dos métodos preferenciais a seguir.

Há dois casos em que fazer chamadas pelo SNIPPET é o método que você deve usar: se você estiver se conectando a um serviço web SOAP ou se suas Chamadas de API incluírem XML. Se você precisar usar o SNIPPET para Chamadas de API:

  • Limite os tempos limite nas suas Chamadas de API. Uma recomendação geral é que os tempos limite não sejam superiores a dois segundos. Os tempos limite padrão podem ser mais longos, portanto, verifique sempre os tempos limite para garantir que eles não excedam esse máximo. Se você constatar que tempos limite mais longos são necessários, ajuste seu serviço web, se possível, para melhorar seus tempos de resposta.
  • Seja extremamente cauteloso com a lógica de Loop. A combinação de Loops e tempos limite longos agrava o impacto potencial no seu sistema.
  • O tamanho máximo da resposta em NiCE CXone é 32 KB. O limite é estritamente aplicado para evitar instabilidade e interrupções no cluster. Studio aplica esse limite ao salvar o script, mas Desktop Studio não aplica. Se possível, use a ação REST API açãoação ou Integration Hub em vez da ação SNIPPET para fazer Chamadas de API. Eles têm o mesmo limite, mas podem suportar uma carga maior. Se você precisar usar a ação SNIPPET, siga estas dicas para reduzir o tamanho dos dados retornados:

    • Filtrar os dados na resposta da API: Por exemplo, se você estiver usando a API de reporting NiCE para obter contatos, você pode filtrar os resultados pelo startDate e endDate do contato. Essa Chamada de API também permite retornar e limitar uma contagem de parte superior de itens. Consulte a documentação da API que acompanha sua integração de script para determinar quais filtragens você pode usar.

    • Atualize a solicitação de API para retornar somente os dados de que você precisa: Por exemplo, se você estiver usando a API de reporting NiCE para obter contatos, você pode usar os campos contactId ou agentId para retornar somente os dados relevantes. Consulte a documentação da API fornecida com a integração de script para determinar quais limites de dados você pode usar.

    • Compilar middleware: Se você não puder realizar nenhuma das opções anteriores, compile um middleware que realize a filtragem com base em critérios personalizados definidos por você. Se fizer isso, certifique-se de que o middleware não adicione latência à chamada.

Conectar-se a Serviços da web RESTful com uma Ação de Snippet

 

Você pode usar Studio scripts para se conectar a API RESTful usando o proxy REST em uma Snippet ação.Você pode acessar esse serviço com a função GetRestProxy(). O proxy REST permite que seus scripts interajam com servidores web remotos. Ele fornece algumas propriedades e funções que você pode usar para isso. As propriedades e funções são descritas mais à frente nesta seção. A plataforma NiCE CXone permite que as API REST retornem até 32 KB de dados. Essa limitação é imposta no nível da plataforma e é estritamente aplicada.

O proxy REST exige o uso de objetos de dados dinâmicos. O tipo de dados dinâmicos permite que seus scripts trabalhem com respostas formatadas em XML e JSON. objetos de Dados dinâmicos podem receber dados nestes formatos e permitir sua leitura. Você também pode criar objetos dinamicamente que podem ser convertidos em XML ou JSON. Essas habilidades são necessárias ao usar API RESTful.

Para usar o proxy REST, adicione uma ação Snippet ao seu script e abra a janela do editor de Snippet. Chame a função GetRESTProxy() usando a seguinte sintaxe:

ASSIGN proxy = GetRESTProxy() 
 proxy.<property | function>([parameters]) 

Para <property | function>, escolha a partir das propriedades e funções descritas nas seguintes seções.

Propriedades

Propriedade Detalhes
StatusCode

Contém o código de status HTTP após uma chamada a MakeRestRequest(). Esta propriedade não pode ser modificada. Se a função falhar, ela não armazenará mais o código de status.

StatusDescription Contém a descrição de status HTTP após uma chamada a MakeRestRequest(). Esta propriedade não pode ser modificada.
ContentType

Permite substituir o cabeçalho de content-type padrão. O padrão é application/x-www-form-urlencoded.

Dependendo da chamada que está fazendo, pode ser preciso alterar o cabeçalho. Por exemplo, se você estiver enviando JSON, deve alterar isso para application/JSON. É necessário alterar esta propriedade.

ProxyTimeoutSeconds Permite que você altere o tempo limite da solicitação. O padrão é 10 segundos. É necessário alterar esta propriedade.

Funções

A tabela a seguir fornece informações sobre as funções disponíveis para uso ao conectar-se a API RESTful. Há outras funções de proxy REST que permitem que você codifique e misture strings.

Função Detalhes
MakeRestRequest(p1, p2, p3, p4)

Executa uma solicitação HTTP para o URL designado, onde:

  • P1: URL da solicitação; string
  • P2: Carga útil para a Chamada de API; string
  • P3: Accept header and response parser selector; Numeric or String:
    • 0: application/json
    • 1: text/xml
    • 2: application/json (ignore corpo da resposta)
    • 3: text/xml (ignore response body)
      • "JSON" - application/JSON
      • "XML - text/xml
  • P4: Verbo da API REST; string
AddHeader Adiciona um cabeçalho personalizado à solicitação HTTP.
ClearHeaders Remove todos os cabeçalhos personalizados adicionados com AddHeader.
currentUnixTimestamp()

Retorna a hora atual como um registro de data/hora Unix. Somente para uso com getRESTProxy(). Saiba mais sobre esta função na página de ajuda Built-In Functions.

Exemplos

ASSIGN proxy = GetRESTProxy()
ASSIGN proxy.ContentType = "application/json"
ASSIGN url = "https://catfact.ninja/fact"
ASSIGN verb = "GET"
ASSIGN result = proxy.MakeRestRequest(url,payload,'JSON',verb)

 

ASSIGN restProxy=GetRESTProxy()

restProxy.AddHeader("x-api-key", "qwer") //Assigning incorrect header for demonstration purposes
restProxy.ClearHeaders()
restProxy.AddHeader("x-api-key", "asdf")
ASSIGN restProxy.ProxyTimeoutSeconds = "2"
ASSIGN restProxy.ContentType = "application/json"

ASSIGN uri = "http://postman-echo.com/post"

DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero" 
ASSIGN beowulfCharacteristics.foe = "Grendel"
ASSIGN payloadJSON = "{beowulfCharacteristics.asJSON()}"

Conectar-se a SOAP Web Services com uma Ação Snippet

Você pode usar serviços da web baseados em SOAP com Scripts do Studio. Isso exige que você importe um WSDL ou Proxy DLL para o Studio. O DLL importado precisa ser autorizado pela NiCE CXone. Após autorizar a DLL, ela é salva na raiz do armazenamento de arquivo do sistema do NiCE CXone.

Usar serviços web SOAP exige assistência da NiCE CXone. Entre em contato com o representante da sua conta para obter mais informações.

Quando você quiser usar um serviço da web baseado em SOAP em um script Studio, você deve criar um snippet. Adicione uma ação Snippet ao seu script. Na janela do editor Snippet, adicione uma instrução USES que nomeie o arquivo DLL proxy que você gerou e armazenou no armazenamento de arquivo da sua unidade de negócios.

O snippet a seguir é um exemplo de uso de um serviço da web baseado em SOAP com um script do Studio:

USES "sf.dll"
cStart="{now}"
sforce=new SforceService()
session=new SessionHeader()
loginResult=sforce.login("demo@nice.com",password6")
sforce.sessionheadervalue=session
session.sessionid=loginResult.sessionid
sforce.url=loginresult.serverUrl

t=new Task()
t.ActivityDate=#"8/20/2050"
t.Description="Call placed by {first }{Last}."
t.Subject="Call @{cStart}"
t.Status="Completed"
t.CallType="Outbound"
t.OwnerId=SF_Agent_ID
t.ReminderDateTime="{cStart}"

SWITCH Type
{
   CASE "CON" { t.WhoId=SF_Obj_ID }
   CASE "LEA" { t.WhoId=SF_Obj_ID }
   CASE "ACC" { t.WhatId=SF_Obj_ID }
   CASE "OPP" { t.WhatId=SF_Obj_ID }
   CASE "CAS" { t.WhatId=SF_Obj_ID }
}
SaveResult=sforce.create(t)
	

Fazer uma Chamada SOAP com um envoltório REST

Esta opção permite que você use metodologias de API REST para fazer chamadas a serviços da web baseados em SOAP. Cada serviço web responde de maneira diferente dependendo de como foi construído. Pode ser necessário modificar o código de exemplo para trabalhar com o serviço que está chamando.

O XML usado não pode incluir aspas duplas quando você o utiliza em uma SNIPPET ação. Você pode usar uma das seguintes alternativas:

  • Substitua cada aspa dupla por {char(34)}, o que insere um caractere de aspas duplas diretamente à string. Esta opção é ilustrada mais à frente nesta seção, no primeiro exemplo da etapa dois.
  • Substitua cada aspa dupla por uma aspa simples ( ' ). Isso é aceitável em XML e em ações SNIPPET. Esta opção é ilustrada mais à frente nesta seção, no segundo exemplo da etapa dois.

Você precisa substituir apenas aspas duplas que aparecem no XML. Atribuições de Variável no código snippet ainda devem ser colocadas entre aspas duplas.

  1. Faça um proxy REST, atribua o cabeçalho ContentType, já que o serviço web ao qual você está se conectando exige isso, e o URL público do serviço web:

    ASSIGN RestProxy = GetRESTProxy() 
    ASSIGN RestProxy.ContentType = "text/xml; charset=utf-8"
    ASSIGN URL = "https://localhost:9031/ssodir/services/

    SSODirectoryService" //Assign the public Webservice UR
  2. Crie o seu envelope SOAP, que é XML formatado para codificar todos os parâmetros exigidos. Você pode fazer isso de duas maneiras:

    • Separe cada linha. Esta opção facilita a leitura.

    • Concatene tudo em uma única linha.

    Exemplos de ambas as opções estão incluídas nesta etapa.

    Este exemplo mostra o envelope separado em linhas. Além disso, este exemplo mostra aspas duplas substituídas por {char(34)}.

    //Sample Payload:
    ASSIGN Payload = ""
    ASSIGN Payload = "{Payload}<?xml version={char(34)}1.0{char(34)} encoding={char(34)}UTF-8{char(34)}?>"
    ASSIGN Payload = "{Payload}<soapenv:Envelope"
    ASSIGN Payload = "{Payload} xmlns:soapenv={char(34)}http://schemas.xmlsoap.org/soap/envelope/{char(34)}"
    ASSIGN Payload = "{Payload} xmlns:xsd={char(34)}http://www.w3.org/2001/XMLSchema{char(34)}"
    ASSIGN Payload = "{Payload} xmlns:xsi={char(34)}http://www.w3.org/2001/XMLSchema-instance{char(34)}>"
    ASSIGN Payload = "{Payload}<soapenv:Body>"
    ASSIGN Payload = "{Payload}<ns1:getIDPList"
    ASSIGN Payload = "{Payload} soapenv:encodingStyle="
    ASSIGN Payload = "{Payload} {char(34)}http://schemas.xmlsoap.org/soap/encoding/{char(34)} "
    ASSIGN Payload = "{Payload}xmlns:ns1="
    ASSIGN Payload = "{Payload} {char(34)}https://localhost:9031/ssodir/services/"
    ASSIGN Payload = "{Payload}  SSODirectoryService{char(34)}/>"
    ASSIGN Payload = "{Payload}</soapenv:Body>"
    ASSIGN Payload = "{Payload}</soapenv:Envelope>"

    A linha a seguir mostra o código do envelope concatenado em uma linha. Neste exemplo, as aspas duplas foram substituídas por aspas simples.

    //Sample Payload:
    ASSIGN Payload = "<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'><soapenv:Body><ns1:getIDPList soapenv:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:ns1='https://localhost:9031/ssodir/services/SSODirectoryService'/> </soapenv:Body></soapenv:Envelope>"
    
  3. Execute a solicitação REST. O exemplo a seguir está sendo executado como um POST.

    Result = RestProxy.MakeRestRequest(URL,Payload,1,"POST")