Usar a API SOAP
Objetivos de aprendizagem
- 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.
WSDL empresarial e do parceiro
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 Configuração, insira API na caixa Busca rápida e selecione API. Na página WSDL da API, clique em Gerar WSDL empresarial.
![Gerar WSDL empresarial](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/10b6825d8fdfc5f2655f99911e9de084_api-basics-soap-wsdl.png)
Na página Gerar WSDL empresarial, clique em 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
Depois de ter instalado e iniciado o SoapUI, no menu Arquivo, selecione 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.
![Como explorar a API SOAP do Salesforce com o SoapUI](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/498f63f3c9a4527f794ca8e073338bd7_api-basics-soap-soapui-1.png)
Clique em OK. Após alguns segundos de processamento, uma pasta chamada 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.
![Pasta SoapBinding do SoapUI](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/0f5e9d7a07b2627d6a373c418971b869_api-basics-soap-soapui-2.png)
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
![Solicitação de login da SOAP de amostra](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/62d42aa58407088ae213fcd183c958c4_api-basics-soap-soapui-3.png)
- 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.
- 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>.
Para obter seu token de segurança, acesse seu configurações pessoais e vá para a página Redefinir minha chave de segurança em Minhas informações pessoais. Clique em Redefinir token de segurança para enviar um e-mail ao endereço associado ao seu Trailhead Playground com seu token.
Sua mensagem SOAP tem mais ou menos essa aparência.
![Uma solicitação de login do SoapUI de amostra com as credenciais de nossa organização DE](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/0ae5c316ad3f5a0ec9c3021534fdc2af_api-basics-soap-soapui-4.png)
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.
![Resposta de login da API SOAP](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/0f10db3ca1db42bcce8faff9a866fad3_api-basics-soap-soapui-5.png)
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.
![O servidor de instância e a ID de sessão estão contidos na resposta de login](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/5054fabc6ff8cf89e18bad0937c952a2_api-basics-soap-soapui-6.png)
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
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.
![Solicitação create() de amostra no SoapUI](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/bafbf8c715f3f13950f2006988f6e804_api-basics-soap-soapui-7.png)
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.
![Solicitação Create() com elementos irrelevantes removida](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/7e603e8941b2e6718766cb4b1a745086_api-basics-soap-soapui-8.png)
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.
![Resposta SOAP para criar uma conta](https://res.cloudinary.com/hy4kyit2a/f_auto,fl_lossy,q_70/learn/modules/api_basics/api_basics_soap/images/pt-BR/e7f77f7cbb0218d069a2b39e1302be0d_api-basics-soap-soapui-9.png)
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.