Tarefa "Ler registro do Salesforce"

Aviso: o Application Integration já está disponível para seu projeto do Google Cloud. Agora é possível usar a Apigee Integration e o Application Integration no mesmo projeto do Google Cloud. Saiba mais

Há dois tipos de tarefas disponíveis na integração da Apigee: tarefas principais e do conector. A tarefa Ler registro do Salesforce é uma tarefa do conector que permite ler um objeto existente do Salesforce na instância do Salesforce.

Antes de começar

Nesta seção, descrevemos as etapas necessárias para conectar e configurar uma instância do Salesforce e usar eventos de Change Data Capture (CDC) ou Platform para fazer streaming das alterações para a integração da Apigee de maneira pub/sub. As etapas a seguir precisam ser concluídas antes de configurar qualquer tarefa ou gatilho relacionado ao Salesforce na integração da Apigee:

• Definir um usuário de integração
• Configurar um conjunto de permissões
• Configurar um token de segurança
• Criar um app conectado

Observação: para concluir essas etapas, é necessário ter acesso de administração do sistema à instância do Salesforce. Se você não tiver acesso de administrador, compartilhe estas instruções com o administrador do Salesforce.

Neste tutorial, fornecemos instruções detalhadas, mas recomendamos que você entenda as opções de configuração do Salesforce. O Salesforce oferece uma documentação para o desenvolvedor detalhada para ajudar você a começar.

Definir um usuário de integração

Observação: se você já tiver um usuário de integração e souber a senha, pule para a próxima etapa. Se você precisar redefinir a senha, consulte a Etapa 6 abaixo.

Configure um usuário de integração com as seguintes etapas:

1. Faça login na instância do Salesforce com as credenciais de sysadmin.
2. Clique no ícone de engrenagem e selecione Configuração, como mostrado na imagem abaixo:
3. Clique em Usuários > Usuários no menu Administração.
4. No painel Usuários, selecione o botão Novo usuário.
5. Na caixa de diálogo Edição do usuário, preencha os seguintes detalhes:
   1. Nome: nome do usuário de integração.
   2. Sobrenome: o sobrenome do usuário de integração.
   3. Endereço de e-mail: e-mail do usuário da integração. O ideal é que seja um e-mail de grupo.
   4. Nome de usuário: nome de usuário de acordo com as convenções de nomenclatura no nível da organização.

      Para criar um novo usuário de integração, use o seguinte formato: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Se você já tiver um usuário de integração, confirme se o nome de usuário foi inserido aqui.

   5. Papel: selecione uma opção no menu suspenso.
   6. Licença do usuário: digite Salesforce ou, se usar uma organização de avaliação, digite Salesforce Platform.
   7. Perfil: selecione o perfil de permissões para os usuários de integração na lista suspensa.

      Recomendamos a atribuição de um perfil sem permissões para proteger o acesso do Salesforce ao usuário de integração contra uso não autorizado.

   8. Clique em Save.
6. Para atualizar a senha do novo usuário de integração, siga estas etapas:
   1. Clique no botão Redefinir senhas no painel Usuários. Um e-mail de redefinição de senha é enviado para o endereço de e-mail associado ao usuário.
      Observação: confirme se você tem acesso à conta de e-mail associada ao usuário da integração antes de acionar o fluxo de redefinição de senha. Além disso, se você tiver ativado o SSO para esse usuário, não será possível redefinir a senha. Para ativar a opção de redefinição, acesse Perfil > Permissões do sistema e desmarque a opção Login com SSO ativado.
   2. Siga as etapas de redefinição de senha na conta de e-mail. Anote a nova senha, porque você precisará dela para uma etapa posterior.

Configurar um conjunto de permissões

Se você já tiver acesso a um conjunto de permissões adequado para um usuário de integração, pule esta etapa e prossiga para Configurar um token de segurança. Caso contrário, siga estas etapas para configurar um conjunto de permissões para o usuário de integração e o objeto do Salesforce.

Para configurar um conjunto de permissões para o usuário de integração:

1. No menu Configuração, clique em Usuários > Conjuntos de permissões.
2. No painel Conjuntos de permissões, clique no botão Novo.
3. Na caixa de diálogo Conjuntos de permissões, insira os seguintes detalhes:
   • Rótulo: insira um nome para o conjunto de permissões.
   • Licença: selecione Salesforce na lista suspensa Licença.
   • Clique em Save.
4. Na lista de opções de configuração Sistema, role para baixo e selecione Permissões do sistema
5. Na página Permissões do Sistema, clique no botão Editar.
6. Role a lista de permissões disponíveis para baixo e marque a caixa de seleção API ativada.

   A permissão Somente usuário da API também é obrigatória, mas não pode ser ativada até que o token de segurança exigido seja redefinido. Essa permissão é adicionada em uma etapa posterior.

7. (Opcional) Role e selecione Modificar todos os dados e Ver todos os dados, se aplicável. Essas permissões não são obrigatórias, mas podem ser úteis se você quiser que o usuário de integração acesse automaticamente novos objetos. Recomendamos ativar essas permissões somente para testes em um sandbox.
8. Role até o topo da lista de permissões e clique em Salvar.
9. Confirme suas configurações e clique em Salvar.

Para configurar o conjunto de permissões para o objeto do Salesforce:

1. Clique em Visão geral do conjunto de permissões para retornar à página de configuração principal Conjunto de permissões.
2. Selecione Configurações do objeto na seção Apps do painel Permissões definidas.
3. Role para baixo e selecione os objetos do Salesforce que exigem um conjunto de permissões. Este exemplo usa o objeto Opportunity.
   OBSERVAÇÃO: o CDC é compatível apenas com um subconjunto de objetos padrão do Salesforce. Para saber mais, consulte: Alterar suporte a objetos de evento.
4. Clique no botão Editar na página de detalhes do objeto.
5. Marque as caixas de seleção dos tipos de registro. Se você souber quais tipos de registro são necessários, selecione-os. Se não souber quais tipos de registro são necessários, selecione todos eles.
6. Marque as caixas de seleção das Permissões do objeto para ativá-las. As opções Ler e Ver tudo são recomendadas.
7. Conceda Acesso de leitura ou Acesso para edição em cada campo de objeto marcando a caixa de seleção correspondente.
   Observação: o acesso de gravação não é necessário para uso com CDC.
8. Role para a parte superior da página e clique em Salvar.

Configurar um token de segurança

Se você tiver criado um token de segurança para o usuário da integração antes e tiver redefinido a senha, um e-mail com um novo token de segurança será enviado automaticamente. Use o novo token e pule para a seção Criar um app conectado.

Caso contrário, siga as etapas abaixo para redefinir o token de segurança do usuário de integração:

1. Faça login no Salesforce como usuário de integração com o nome de usuário e a senha definidos em uma etapa anterior.
2. No menu principal, clique na foto do perfil e em Configurações.
3. No menu Configurações, selecione Redefinir meu token de segurança para abrir o painel Redefinir token de segurança.
4. Clique no botão Redefinir token de segurança.
5. Procure na conta de e-mail associada ao usuário de integração um e-mail contendo o novo token de segurança. Anote o novo token de segurança, porque você precisará dele para uma etapa posterior.
6. (Opcional) Ative a permissão Somente usuário da API nas Permissões do sistema do seu conjunto de permissões, conforme descrito em Configurar uma permissão acima.

Criar um app conectado

A permissão de administração do sistema é necessária para configurar um app conectado. Se você estiver conectado como um usuário de integração, saia e faça login novamente como sysadmin.

Siga estas etapas para configurar um aplicativo conectado:

1. Clique no ícone de engrenagem e selecione Configuração.
2. No menu Configuração, procure e selecione Gerenciador de aplicativo, como mostrado na imagem abaixo:
3. Clique em New Connected App.
4. No painel de configuração, forneça os detalhes a seguir:
   • Nome do app conectado: digite um nome para o app conectado.
   • Nome da API: digite o nome da API.
   • E-mail de contato: informe um e-mail para seu app conectado, de preferência um alias de e-mail de grupo.
   • API (ativar configurações do OAuth): selecione Ativar configurações do OAuth. Em seguida, defina o seguinte:
     1. (Opcional) URL de callback: só será necessário se você quiser que um serviço externo realize a validação. Se você optar por fornecer um callback, inclua o prefixo http(s)://.
     2. Escopos do OAuth selecionados: selecione:
        • Acessar e gerenciar seus dados (API)
        • Faça solicitações em seu nome a qualquer momento (refresh_token, offline_access)
5. Clique em Save.
   Observação: o app conectado recém-criado não funcionará nos primeiros 2 a 10 minutos após a criação.
6. Clique em Continuar.
7. Um secret do cliente e uma chave do cliente serão exibidos na próxima página. Anote esses valores, porque eles serão usados ao configurar o módulo de autenticação para a Apigee.
8. Clique no botão Gerenciar.
9. Na página Detalhes do app conectado, clique no botão Editar políticas.
10. Na seção Políticas do OAuth, altere o valor no menu suspenso Usuários permitidos para Usuários aprovados por administradores são pré-autorizados.
11. Clique em Save.
12. Role até a seção Perfis e Conjuntos de permissões da página para selecionar o perfil ou o conjunto de permissões que você quer aplicar ao app conectado.
    Você pode selecionar um perfil, um conjunto de permissões ou uma mistura de ambos, o que permitirá que os usuários com o perfil ou o conjunto de permissões correto acessem o aplicativo conectado.
13. Selecione o perfil ou o conjunto de permissões desejado.
14. Clique em Save.

Authentication

Para usar essa tarefa, você precisa configurar um perfil de autenticação com as credenciais de cliente do OAuth 2.0. As integrações da Apigee usam o perfil de autenticação para se conectar à instância do Salesforce. Para criar um perfil de autenticação, execute as seguintes etapas:

1. Nas propriedades editáveis da tarefa, clique em +Novo perfil de autenticação para abrir a caixa de diálogo Perfil de autenticação.
2. Defina as seguintes propriedades:
   • Em Tipo de autenticação, selecione Credenciais de senha do proprietário dos recursos do OAuth 2.0.
   • Endpoint do token:
     • No sandbox, insira https://test.salesforce.com/services/oauth2/token
     • Na produção, insira https://login.salesforce.com/services/oauth2/token
   • ID do cliente: insira o identificador exclusivo do cliente.

     O ID do cliente é o token do cliente do app conectado. É possível encontrar o token do cliente na página Gerenciar apps conectados ou na definição do app conectado.

   • Secret: insira a chave secreta do cliente.

     A chave secreta do cliente é a chave do consumidor do app conectado. É possível encontrar a chave secreta do consumidor na página Gerenciar apps conectados do app conectado ou na definição do app conectado.

   • Escopo(s): escopo do token de acesso.

     Os escopos permitem especificar permissões de acesso para os usuários. É possível especificar vários escopos separados por um espaço.

   • Nome de usuário: nome de usuário para autenticação.
   • Senha: senha do usuário.
   • Tipos de solicitações: selecione um dos seguintes valores:
     • Parâmetros de consulta
     • Corpo da solicitação

     O tipo de solicitação selecionado deve ser compatível com a instância do Salesforce.

   • Parâmetros de token: parâmetros de solicitação necessários para receber o token.
   • Nome do perfil de autenticação: nome do perfil de autenticação.
   • Descrição do perfil de autenticação: descrição do perfil de autenticação.
   • Certificado SSL: faça upload do certificado SSL/TLS e da chave privada correspondente.

     Se a chave privada tiver uma senha longa, insira-a.

3. Clique em Save.

Configurar a tarefa "Ler registro do Salesforce"

Para configurar a tarefa Ler registro do Salesforce:

1. Acesse a IU da Apigee e faça login.
2. Selecione a organização usando o menu suspenso no canto superior esquerdo da IU.
3. Clique em Desenvolver > Integrações.
4. Busque ou selecione a integração para fazer edições na lista Integrações e clique para abrir o designer de integração.
5. Clique em +Adicionar uma tarefa/gatilho > Tarefas para ver a lista de tarefas disponíveis.
6. Arraste o elemento da tarefa Ler registro do Salesforce para o designer de integração.
7. Clique no elemento da tarefa Ler registro do Salesforce no designer para abrir o painel de configuração da tarefa Ler registro do Salesforce.
8. Escolha o Perfil de autenticação criado anteriormente no menu suspenso Autenticação.
9. Configure os campos restantes usando as propriedades de configuração da tarefa.
10. As alterações nas propriedades são salvas automaticamente.

Propriedades de configuração

A tabela a seguir descreve as propriedades de configuração da tarefa Ler registro do Salesforce.

Propriedade	Tipo de dado	Descrição
Domínio do Salesforce	String	Nome da instância do Salesforce a que você quer se conectar. O domínio do Salesforce está disponível no URL da instância do Salesforce. Por exemplo, INSTANCE_NAME.my.salesforce.com.
Versão da API Salesforce	String	Versão atual da API na sua instância do Salesforce. A versão atual da API está disponível na instância do Salesforce em Configuração > API > Gerar WSDL de parceiro.
Nome do objeto	String	Nome do objeto do Salesforce que você quer ler.
ID do registro	String	ID do registro a ser atualizado. O valor do código é criado automaticamente quando você insere um registro. O valor do ID identifica exclusivamente o registro e não muda durante a vida útil do registro.
Record	String	Retorna o valor da tarefa. Se a operação de leitura for bem-sucedida, essa variável conterá os detalhes do objeto do Salesforce que é lido.

Tentar novamente em caso de falha

É possível configurar várias estratégias de repetição para lidar com erros em uma tarefa. As estratégias de repetição permitem especificar como executar novamente a tarefa em caso de erro. Para mais informações, consulte Estratégias de tratamento de erros.

Considerações

Os limites de cota na sua instância do Salesforce podem afetar o uso dessa tarefa. Fale com o administrador do Salesforce para garantir que o design de integração seja compatível com a cota do Salesforce.