Chamadas de API do serviço web

Todas as chamadas de API WS devem estar contidas em uma solicitação HTTP com os cabeçalhos HTTP apropriados. Todas as chamadas de API WS do Service Desk requerem os seguintes argumentos padrão:

Argumento	Descrição
	Credenciais
authorizationToken	O Token de autorização para o cliente do serviço web
sliceToken	O token do slice para o cliente do serviço web
username	O nome de usuário do cliente para o cliente do serviço web
userPassword	A senha de usuário do cliente para o cliente do serviço web
	Configurações estendidas
responseFormat	Formato de dados de saída do serviço web (JSON, XML e JavaBean)

Esta seção contém os seguintes tópicos:

Resposta a todas as chamadas:

A resposta a todas as chamadas de API WS da Central de atendimento compreende uma classe de bean padrão de resposta do serviço, independentemente de a solicitação ser bem-sucedida ou não. A classe do bean de obtenção de resposta pode conter os integrantes a seguir:

Integrantes	Descrição
	Resposta de serviço padrão
responseStatus	O status da mensagem de saída de uma invocação de serviço web
statusCode	O código de status da resposta do serviço web
statusMessage	Mensagem de status da resposta do serviço web
responseFormat	O formato da mensagem de saída de uma chamada de serviço web
responseText	O texto formatado da mensagem de saída (aplicável aos tipos de formato XML, JSON)
responseBean	A classe de bean de saída específica do serviço (aplicável quando o formato da resposta for BEAN).
erros	A lista de mensagens de erro que ocorreram durante a invocação de serviço web.
warnings	A lista de mensagens de aviso informando o cliente sobre problemas não fatais ou condições que podem causar problemas.
observações	A lista de mensagens informativas para transmitir informações ou melhorar o diagnóstico.

A chamada get

A chamada get é usada para recuperar um conjunto predefinido de valores de campo para uma entidade com base no identificador do registro.

A solicitação get

Além dos argumentos normais de ID de logon e senha, a chamada get também requer o seguinte argumento:

Integrantes	Descrição
Identificador de registro	Identificador de registro (ID de linha) da entidade

A resposta de get

A resposta padrão do serviço para todas as chamadas de API conterá o registro no formato de saída solicitado para uma chamada get.

A chamada list

A chamada list é usada para recuperar registros (entidades) com base nos critérios de pesquisa especificados.

A solicitação list: além dos argumentos normais de ID de logon e senha, a chamada list também requer os seguintes argumentos:

Integrantes	Descrição
Texto da pesquisa	Valor do texto de pesquisa a ser procurado no conjunto de campos identificados para uma entidade.

A resposta de list

A resposta padrão do serviço para todas as chamadas de API conterá o conjunto de registros correspondentes aos critérios de pesquisa no formato de saída solicitado para uma chamada list.

A chamada insert

A chamada insert é usada para criar um novo registro (entidade) de um tipo específico com os valores especificados.

A solicitação insert - além dos argumentos normais de ID de logon e senha, a chamada insert também requer os seguintes argumentos:

Integrantes	Descrição
Classe do bean	Classe de bean java bean (dados complexos) específica da entidade que contém valores para os campos que devem ser definidos ao criar a entidade.

Durante uma inserção, não é necessário especificar todos os campos desse tipo de entidade. A maioria dos campos é opcional, exceto aqueles marcados como obrigatórios na resposta de descrição, indicados pelo atributo 'anulável' com o valor booleano '0'. Os campos não especificados são definidos como em branco ou com valores padrão. Os campos muito longos são truncados.

Quando você enviar valores de campo não reconhecidos na solicitação insert, a API do serviço web rejeitará a chamada. Como resultado, o código de status 300 é transmitido, conforme indicado pela seguinte mensagem:

Rejecting the value that is supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

A API aplica uma definição estrita dos valores de campo não reconhecidos, de modo que todos os campos da chamada precisem ser válidos para o usuário da operação.

Por exemplo:

A API rejeita chamadas que especificam um valor para um campo personalizado que tenha sido excluído ou removido do acesso de um usuário.
A API rejeita chamadas que especificam campos somente leitura.

Para alguns tipos de entidades, se você inserir um registro que já existia, a API não insere novos registros.

A resposta de insert

A resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo inserido no formato de saída solicitado para uma chamada insert.

A chamada update

A chamada update é usada para modificar um registro (entidade) existente identificado pelo identificador de registro com valores especificados.

A solicitação update

Além dos argumentos normais de ID de logon e senha, a chamada update também requer os seguintes argumentos:

Integrante: classe do bean

Descrição: classe de bean de java (tipo de dados complexos) específica da entidade que contém valores para os campos que devem ser atualizados, durante a atualização de uma entidade existente identificada pelo identificador de registro.

Durante uma atualização, não é necessário especificar todos os campos desse tipo de entidade. Transmita os valores para os campos que deseja atualizar durante a chamada.

Os campos não especificados serão mantidos intactos. Os campos muito longos são truncados. Se você enviar valores de campo não reconhecidos na solicitação update, a API WS da Central de atendimento rejeitará a chamada e enviará o código de status 300 com uma mensagem de status associada que indica o seguinte:

Rejecting the value supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.

A API aplica uma definição estrita dos valores de campo não reconhecidos, de modo que todos os campos da chamada precisem ser válidos para o usuário da operação. Por exemplo: a API rejeita chamadas que especificam um valor para um campo personalizado que tenha sido excluído ou removido do acesso de um usuário.
A API rejeita chamadas que especificam campos somente leitura.

A resposta de update: a resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo atualizado no formato de saída solicitado para uma chamada update.

É possível limpar os campos de texto que não são obrigatórios inserindo ##NULL##. No entanto, se você digitar ##NULL## em um campo obrigatório, você irá receber a mensagem padrão informando que o campo é obrigatório.

Quando um usuário tenta atualizar o ticket, é exibida uma mensagem de erro indicando que os seguintes campos são campos somente leitura:

Organização do solicitante
Local do solicitante
Site do solicitante
Solicitado para – Organização
Solicitado para o local
Solicitado para o site
Caso de pai

A chamada delete

A chamada delete é usada para excluir um registro (entidade) existente identificado pelo identificador de registro.

A solicitação delete - além dos argumentos normais de ID de logon e senha, a chamada delete também requer o seguinte argumento:

Integrantes	Descrição
Identificador de registro	Identificador de registro (ID de linha) de um registro

A resposta de delete

A resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo excluído no formato de saída solicitado para uma chamada delete.

A chamada relate

A chamada relate é usada para relacionar uma entidade (registro) com outra entidade identificada pelos seus respectivos identificadores de registro.

A solicitação relate: além dos argumentos normais de ID de logon e senha, a execução de relate também requer o seguinte:

Integrantes	Descrição
Identificador de registro	Identificador de registro (ID de linha) de uma entidade à qual outra entidade deve estar relacionada
Identificador de registro relacionado	Identificador de registro (ID de linha) de uma entidade que deve ser relacionada a outra entidade

A resposta relate: a resposta padrão do serviço para todas as chamadas da API pode conter o identificador de registro (ID de linha) de um registro que está sendo inserido na tabela de relacionamentos no formato de saída solicitado para uma chamada relate.

A chamada unrelate

A chamada unrelate é usada para cancelar a relação de um registro de entidade com outra entidade identificada pelos seus respectivos identificadores de registro.

A solicitação unrelate - além dos argumentos normais de ID de logon e senha, a chamada unrelate também requer os seguintes argumentos:

Integrantes	Descrição
Identificador de registro	Identificador de registro (ID de linha) de uma entidade cuja relação com outra entidade deve ser cancelada.
Identificador de registro relacionado	Identificador de registro (ID de linha) de uma entidade cuja relação com outra entidade deve ser cancelada.

A resposta de unrelate: a resposta padrão do serviço para todas as chamadas de API pode conter o identificador de registro (ID de linha) de um registro que está sendo inserido na tabela de relacionamentos no formato de saída solicitado para uma chamada relate.

Segurança do campo

A API WS do Service Desk impõe o modelo de segurança de campo que está configurado na interface do usuário do Service Desk. Nessa interface, certos campos podem ser marcados como somente leitura ou podem estar ocultos em layouts de página.

Para um usuário específico, a API pode acessar apenas os campos que são acessíveis a esse usuário em seu layout de página atribuído. As seguintes restrições se aplicam:

A API pode consultar campos somente leitura, mas não pode inserir ou atualizar esses campos para esse usuário.
A API não pode consultar, inserir ou atualizar os campos marcados como ocultos para esse usuário.

Com a API WS do Service Desk, os campos ocultos não são visíveis para nenhum usuário, mesmo aqueles que possuem privilégios totais. Esse comportamento é consistente com o funcionamento do aplicativo.

Campos numéricos

Os campos numéricos incluem os campos do tipo número inteiro e duplo. Os campos padrão predefinidos são do tipo número inteiro ou duplo, de acordo com os critérios explicados na seção Determinando o tipo de campos padrão. Todos os campos numéricos personalizados são tratados como tipo duplo.

Os campos numéricos devem ser transferidos como tipo i4 ou duplo, conforme apropriado, com exceção de que é possível definir um campo numérico como nulo definindo-o com um valor de sequência de caracteres em branco. O tipo de é indicado na resposta de descrição de uma entidade.

O tipo deve ser respeitado em todas as futuras chamadas que se referirem a esse campo, inclusive nas chamadas insert e update. O tipo do campo também é retornado pela chamada query.

Os limites do campo numérico são impostos quando os registros são inseridos ou atualizados. Os limites são indicados na resposta de descrição pelo atributo ‘dígitos’ para um campo de número inteiro ou pelos atributos ‘escala’ e ‘precisão’ para um campo duplo.

Integrantes	Descrição
Dígitos	Especifica o número máximo de dígitos que pode ter um número inteiro
Definir a escala	Para campos duplos, especifica o número máximo de dígitos à direita da vírgula decimal.
Precisão	Para campos duplos, especifica o número total de dígitos, incluindo aqueles à esquerda e à direita da vírgula decimal.

O número máximo de dígitos à esquerda da vírgula decimal é igual à ‘precisão’ menos ‘escala’. Na interface do usuário da Central de atendimento, a precisão é definida de forma diferente; é o número máximo de dígitos permitidos à esquerda da vírgula decimal.

Os limites dos campos numéricos são impostos quando os dados são inseridos ou atualizados. No entanto, a API WS da Central de atendimento pode retornar dados que não atendam a essas restrições.