Usar a API SOAP
Objetivos de aprendizagem
Após concluir esta unidade, você estará apto a:
- Gerar um arquivo WSDL para sua organização.
- Usar o SoapUI para criar um projeto SOAP a partir de um arquivo WSDL.
- Fazer login no Trailhead Playground usando a API SOAP.
- Criar uma conta usando a API SOAP.
Nota
Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.
Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.
WSDL empresarial e do parceiro
Se você percorreu o caminho de outra API baseada em SOAP, sabe que o arquivo WSDL (Web Services Description Language, Linguagem de Descrição de Serviços Web) é basicamente seu mapa para entender como usar a API. Ele contém as vinculações, os protocolos e os objetos para fazer chamadas de API.
O Salesforce fornece duas WSDLs da API SOAP para dois casos de uso diferentes. A WSDL empresarial é otimizada para uma organização do Salesforce individual. É fortemente tipada e reflete a configuração específica de sua organização, isto é, dois arquivos WSDL empresariais gerados de duas organizações diferentes contendo informações diferentes.
A WSDL do parceiro é otimizada para ser usada com muitas organizações do Salesforce. É vagamente tipada e não se altera de acordo com a configuração específica de uma organização. Geralmente, se você estiver escrevendo uma integração para uma organização do Salesforce individual, use a WSDL empresarial. Para muitas organizações, use a WSDL do parceiro.
Para esta unidade, estamos usando a WSDL empresarial para explorar a API SOAP. A primeira etapa é gerar um arquivo WSDL para sua organização. Em seu Trailhead Playground, em Setup (Configuração), insira API na caixa Busca rápida e selecione API. Na página WSDL da API, clique em Generate Enterprise WSDL (Gerar WSDL empresarial).
Na página Generate Enterprise WSDL (Gerar WSDL empresarial), clique em Generate (Gerar). Quando o WSDL for gerado, clique com o botão direito do mouse na página e salve o WSDL como um arquivo XML em algum lugar no computador. Vamos usá-lo daqui a pouco.
Aqui fica uma dica para trabalhar com a WSDL empresarial. A WSDL empresarial reflete a configuração específica de sua organização, então, sempre que você fizer uma alteração de metadados em sua organização, deve gerar novamente o arquivo WSDL. Dessa forma, o arquivo WSDL não fica fora de sincronia com a configuração de sua organização.
Criar um projeto SOAP com SoapUI
Agora que temos nosso arquivo WSDL, precisamos de uma maneira de extrair informações para começar a fazer solicitações à API SOAP. Na linguagem da Web, esse processo é chamado consumo de WSDL. Assim como o kraken consome uma embarcação cheia de marinheiros desafortunados, ferramentas como o Web Services Connector (WSC) consomem o arquivo WSDL. As ferramentas criam, então, classes que permitem que você faça solicitações com a API SOAP usando linguagens de programação comuns.
Para esta unidade, estamos usando uma ferramenta de terceiros chamada SoapUI para consumir nosso arquivo WSDL empresarial. O SoapUI é um aplicativo gratuito e de código aberto para testar serviços Web. Para começar, baixe e instale o SoapUI OpenSource no site do SoapUI. Instale somente o componente SoapUI.
Certifique-se de que a versão do Java que o SoapUI agrupa e usa é compatível com as políticas de segurança da sua organização. Você pode encontrar a versão do Java que o SoapUI usa selecionando Help (Ajuda) | System Settings (Configurações do sistema) de dentro do SoapUI. Consulte www.soapui.org para obter mais informações.
Depois de ter instalado e iniciado o SoapUI, no menu File (Arquivo), selecione New SOAP Project (Novo projeto SOAP). Para o nome do projeto, insira Como explorar a API SOAP do Salesforce. Para a WSDL inicial, navegue para onde você salvou o arquivo WSDL empresarial e selecione-o. Não altere nenhuma outra opção. Sua janela do SoapUI tem mais ou menos essa aparência.
Clique em OK. Após alguns segundos de processamento, uma pasta chamada Exploring Salesforce SOAP API (Como explorar a API SOAP do Salesforce) aparece no painel do navegador no lado esquerdo da tela. Abaixo dela está uma entrada chamada SoapBinding que contém várias operações.
Então para o que estamos olhando aqui? Cada operação corresponde a uma solicitação à API SOAP que podemos fazer. As propriedades de cada operação são extraídas de informações no arquivo WSDL. Cada operação também contém uma solicitação XML de amostra que inclui o ponto de extremidade HTTPS da operação e uma mensagem SOAP pré-preenchida.
Só mais uma coisa: o Salesforce requer que todas as conexões usem TLS 1.2 ou superior. Se você está usando SoapUI com Java7, o TLS 1.2 não está habilitado por padrão. Ao tentar se conectar ao Salesforce com uma versão antiga de TLS, você receberá uma mensagem de erro. A boa notícia é que isso é fácil de corrigir. Confira essa publicação no blog para saber mais.
Agora estamos todos preparados para fazer solicitações à API SOAP. Preparados para zarpar, capitão!
Fazer login no Trailhead Playground
No SoapUI, role para baixo até a operação login. Expanda e clique duas vezes em Request 1 (Solicitação 1). Uma solicitação de login da SOAP de amostra aparece.
Aqui está o URI (1) do ponto de extremidade em detalhes.
- https://– especifica HTTP seguro.
- login.salesforce.com – Domínio de nível superior para uma solicitação de login.
- /services/Soap – Especifica que estamos fazendo uma solicitação à API SOAP.
- /c – Especifica que estamos usando a WSDL empresarial. Use /u para a WSDL do parceiro.
- /36.0 – Número de versão da API. O prefixo v está faltando porque algumas APIs o incluem antes do número de versão e outras não. Esse comportamento é apenas uma peculiaridade das APIs do Salesforce.
- /0DF36000000LHZw – Número da versão de pacote.
Não estamos usando pacotes gerenciados neste exemplo, então podemos remover o número da versão de pacote do final da URI. Faça isso agora.
A mensagem SOAP (2) contém tudo o que esperamos encontrar em uma mensagem SOAP: um envelope, um cabeçalho e um corpo.
As propriedades dentro do elemento LoginScopeHeader referem-se à autenticação dos usuários no Portal de autoatendimento e no Portal de clientes. Uma vez que não temos que nos preocupar com esses valores para os nossos propósitos, exclua completamente o elemento <urn:LoginScopeHeader> (tudo de <urn: LoginScopeHeader> até </urn:LoginScopeHeader>). Destaque o texto na janela e pressione a tecla Delete.
Depois, olhe para o elemento <urn:login> no corpo da mensagem. Esse elemento é o grosso da solicitação de login. É onde fornecemos as credenciais de nossos usuários. Substitua os ? pelo seu nome de usuário e senha para o Trailhead Playground.
Para tal, suas credenciais do Trailhead Playground são necessárias. No Iniciador de aplicativos, encontre e abra o Playground Starter e siga as etapas abaixo. Se você não vir o aplicativo Playground Starter, consulte Encontrar o nome de usuário e a senha para seu Trailhead Playground na Ajuda do Salesforce.
- Clique na guia Obter suas credenciais de login e anote seu nome de usuário.
- Clique em Redefinir minha senha. Isso envia um email para o endereço associado ao seu nome de usuário.
- Clique no link no email.
Visto que você está fazendo uma solicitação de API de um endereço IP desconhecido para o Salesforce, você precisa anexar seu token de segurança ao final de sua senha. Por exemplo, se sua senha é mypassword e seu token de segurança é XXXXXXXXXX, insira mypasswordXXXXXXXXXX dentro do elemento <urn:password>.
Clique no seu avatar no canto superior direito da tela, selecione Settings (Configurações) e, em seguida, escolha Reset My Security Token (Redefinir meu token de segurança) em My Personal Information (Minhas informações pessoais). Clique em Redefinir token de segurança (Redefinir token de segurança) para enviar um email ao endereço associado ao seu Trailhead Playground com seu token.
Sua mensagem SOAP tem mais ou menos essa aparência.
Clique no botão de reprodução (triângulo verde) no canto superior esquerdo da janela de solicitação. Esse botão envia a solicitação, jogando sua mensagem SOAP em uma garrafa no mar. Veja como ela fica quando expandimos a resposta.
Parabéns, capitão. Você fez login corretamente. A resposta contém uma série de informações sobre sua organização e usuário. Ainda mais importante, contém o nome do Meu domínio da sua organização e uma ID de sessão que vamos usar para fazer futuras solicitações e que é destacada aqui.
Copie a instância e a ID de sessão para um arquivo de texto. Vamos usá-las daqui a pouco.
Como é provável que a instância da sua organização mude, não codifique referências para a instância quando começar a criar as integrações! Em vez disso, use a URL de login do Meu domínio da sua organização. Com Meu domínio, você configura um domínio específico do cliente para sua organização do Salesforce. O Meu domínio, além de eliminar a dor de cabeça de alterar nomes de instância, também pode ser usado para destacar sua marca, tornar sua organização mais segura e personalizar sua página de login.
Criar uma conta
Assim como fizemos com a API REST, vamos criar uma conta com a API SOAP. No painel de navegação à esquerda da tela, encontre a operação create. Expanda-a e clique duas vezes em Request 1 (Solicitação 1).
Porque criar um registro é mais complicado que fazer login, a mensagem SOAP create() inclui muito mais elementos. A maioria dos elementos está contida no cabeçalho de solicitação e a maior parte deles é opcional. Para simplificar, vamos excluir a maioria das informações de cabeçalho; mas lembre-se de que as opções fornecidas por esses cabeçalhos estão disponíveis quando você cria um registro. Para obter informações sobre o que faz cada cabeçalho, veja o tópico Cabeçalhos SOAP no Guia do desenvolvedor da API SOAP.
Um cabeçalho que não queremos excluir, contudo, é SessionHeader. Ele vai conter a ID de sessão obtida da resposta login(). Exclua os outros cabeçalhos, de <urn:EmailHeader> até </urn:AssignmentRuleHeader>. Sua mensagem tem essa aparência.
Obtenha a ID de sessão que você copiou para um arquivo de texto e cole-a dentro da marca <urn:sessionId>, substituindo o ?.
Temos mais alguns ajustes para fazer no corpo da mensagem. Primeiro, especificamos que estamos criando uma conta. Altere o texto na marca <urn:sObjects> para ficar assim: <urn:sObjects xsi:type="urn1:Account" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> . Esse ajuste especifica o tipo de registro correto usando a declaração de esquema de instância XML.
Também queremos dar um nome à conta. Adicione <Name>Sample SOAP Account</Name> dentro do elemento sObjects. Exclua fieldsToNull, bem como elementos de Id. Agora sua mensagem tem mais ou menos essa aparência.
Uma última coisa a ser feita antes de fazer a solicitação. Altere o ponto de extremidade para especificar a instância de sua organização em vez de login, e remova a versão de pacote do final do URI. O URI do ponto de extremidade é algo como: https://MyDomainName.trailblaze.develop.my.salesforce.com/services/Soap/c/36.0.
Estamos prontos para enviar a solicitação. Clique no triângulo verde novamente. Funcionou! Vamos ver a resposta.
Observe o LimitInfoHeader. Este cabeçalho retorna informações sobre o uso de API. No exemplo acima, fizemos 9 das 100.000 chamadas permitidas hoje.
No corpo da resposta, observe o elemento de <resultado>. <success>true</success> indica que o registro foi criado com êxito. O <ID> inclui a ID do registro, a qual pode ser usada em futuras solicitações.
Abordamos os conceitos básicos de como fazer solicitações com a API SOAP. Obviamente, cada operação tem seus próprios parâmetros e peculiaridades. Use o Guia do desenvolvedor da API SOAP como seu mapa quando começar a escrever integrações com a API SOAP.
Recursos
- SOAP API Developer Guide
- SOAP API Cheatsheet
- SOAP API Sample WSDL Structures
- SOAP API Web Services Connector (WSC)
- SoapUI Homepage