REST para o vendedor turístico: como usar os dados do Google em Salesforce.com

Lane LiaBraaten, Programas para Desenvolvedores do Google
Novembro de 2007

Introdução

O Salesforce.com e o Google hospedam aplicativos conhecidos como "software como serviço", e ambas as organizações oferecem APIs que permitem aos desenvolvedores acessar os grandes armazenamentos de dados que alimentam esses aplicativos. Assim, as coisas começam a ficar interessantes quando combinamos os dois conjuntos de APIs. O G Suite continua sendo usado cada vez mais no ambiente corporativo, e o Salesforce.com criou uma plataforma abrangente para a criação de aplicativos empresariais personalizados, por isso há muitas oportunidades para os desenvolvedores combinarem o poder do Google com o Salesforce.com.

Este artigo mostra como usar as APIs RESTful de dados do Google para começar a criar mashups empresariais, mesmo que você esteja começando a usar a plataforma Salesforce.com ou o protocolo de dados do Google. Vou ajudar você a configurar seu ambiente de desenvolvimento, instalar um mashup do Google e do Salesforce.com e escrever seu próprio ambiente.

Olá, Salesforce.com.

Se você é um novato no Salesforce.com como eu, comece se inscrevendo em uma conta de desenvolvedor na ADN, a Apex Developer Network. A conta de desenvolvedor oferece uma conta completa do Salesforce.com, além de acesso à wiki do Apex e aos fóruns de discussão.

Agora é hora de instalar o Apex Toolkit para Eclipse. O kit de ferramentas requer o Java 1.5 e o Eclipse 3.2.2 ou uma versão mais recente. Se você souber usar o Eclipse, o site de atualização de software do kit de ferramentas será http://www.adnsandbox.com/eclipsetoolkit/10.0/. Se você não estiver familiarizado com os plug-ins do Eclipse ou algo der errado com sua instalação, a wiki do Apex incluirá instruções detalhadas para a instalação.

Depois da instalação do kit de ferramentas, você poderá acessar o conteúdo de ajuda do Apex que está integrado ao sistema de ajuda do Eclipse. No Eclipse, acesse Help | Contents | | Apex Toolkit for Eclipse para ver esse conteúdo. Um dos recursos de ajuda é um tutorial de início rápido que mostra como criar um novo projeto e adicionar S-Controls, classes e gatilhos. Se você nunca trabalhou com código Apex, faça este tutorial e crie um projeto Apex antes de continuar.

Exportar eventos para o Google Agenda

Ron Hess criou um aplicativo de mashup do Google Agenda que permite exportar eventos do Salesforce.com para o Google Agenda. Ron também escreveu um artigo que explica como o mashup funciona. O aplicativo de planilhas do Google que vou mostrar como criar mais tarde é modelado de acordo com o mashup do Google Agenda de Ron. Obrigado, Ron.

Se você é um usuário avançado do Salesforce.com, provavelmente pode integrar e usar o aplicativo Google Agenda do Ron sem instruções. Eu precisava de uma pequena ajuda no início, então aqui está o que eu fiz para ver o app do Ron em ação.

  1. Instale o aplicativo:
    • Acesse a página do mashup do Google Agenda e clique em Obter agora.
    • Digite suas credenciais da ADN e clique em Continuar.
    • Leia os Termos e Condições e clique em Continuar.
    • Clique em Next na página "Examine package content".
    • Escolha um nível de segurança e clique em Próxima.
    • Clique em Instalar.
  2. Configurar o proxy AJAX do Salesforce.com
    • No menu "Configuração de administração", clique em Controles de segurança | Configurações remotas do site.
    • Clique em Novo site remoto.
    • Insira Google como o "Nome do site remoto" e, em "URL do site remoto", use https://www.google.com.
    • Clique em Salvar.
  3. Adicione o botão "Adicionar ao Google" à página de detalhes do evento:
    • No menu "Configuração do app", clique em Personalizar | Atividades | Layouts de página de evento.
    • Clique em Editar na linha "Layout do evento".
    • Clique duas vezes na área "Botões da página de detalhes".
    • Destaque "Adicionar ao Google" e clique na seta para a direita (>) para adicionar o botão.
    • Clique em OK.
    • Clique em Salvar na página "Propriedades de layout da página".
  4. Exportar um evento
    • Clique em Página inicial no canto superior esquerdo para ver sua agenda.
    • Se você não tiver eventos, clique em Novo evento para criar um.
    • Clique em um evento para ver a página "Detalhes do evento".
    • Clique no botão Adicionar ao Google.
    • Clique em OK no alerta do JavaScript.
    • Faça login com seu nome de usuário e senha do Google.
    • Clique em Conceder acesso para conceder ao aplicativo SalesForce acesso de gravação ao seu Google Agenda.
    • Ver o evento no Google Agenda

Como criar um aplicativo do Planilhas Google

É provável que você esteja cansado de clicar nas páginas do Salesforce.com e estiver pronto para escrever um código. Inicie o Eclipse novamente e você verá que o projeto Apex que você criou agora contém os S-Controls para o aplicativo Ron do Google Agenda. Isso acontece porque o Apex Toolkit para Eclipse está constantemente sincronizando com o Salesforce.com-muito legal, não é?

Você pode criar seu próprio app de dados do Google reutilizando algumas funcionalidades do Mash-up do Google Agenda, como os controles de autenticação. Nesta seção, vamos mostrar como criar um app que exporta seus contatos do Salesforce.com para uma planilha do Google.

Como publicar um controle S simples

Um S-Control é um arquivo hospedado pelo Salesforce.com e executado em navegadores da Web quando os usuários acessam seu aplicativo. Um S-Control pode ter qualquer tipo de conteúdo que possa ser exibido ou executado em um navegador da Web, como HTML, CSS ou JavaScript.

Há algumas partes em movimento em um mashup do Google e do Salesforce.com. A primeira coisa que eu fiz foi adicionar um botão "Exportar para o Google" à página da lista de contatos que invoca um S-Control simples apenas para garantir que todo o encanamento estivesse correto antes de me acostumar com o JavaScript.

No seu projeto Apex, clique com o botão direito do mouse na pasta "S-Controls" e escolha Apex | New S-Control. Atribua um rótulo e um nome ao novo S-Control export_contacts, deixe o tipo como HTML personalizado e clique em Finish.

O novo S-Control conterá um arquivo HTML básico. Você vai adicionar muitos JavaScripts em <head>, mas é possível preencher o <body> primeiro para que haja algo a ser mostrado ao usuário durante a exportação dos contatos. Copie este HTML no corpo do seu S-Control para mostrar os "pontos de espera" e um logotipo do Planilhas Google:

<div id="waiting" align="center" />
  <img src="/img/icon/home32.png" height="64" width="64" />
  <img src="/img/waiting_dots.gif" alt="Please wait..." title="Please wait..." height="25" width="196" />
  <img src="http://docs.google.com/images/doclist/logo_docs.gif" />
  <p><h3>Exporting contacts to Google Spreadsheets, please wait...</h3></p>

</div>

Agora é possível publicar o S-Control e configurar um botão para invocá-lo.

  1. Use o Eclipse para publicar o arquivo S-Control:
    • Clique com o botão direito do mouse no seu projeto Apex e selecione Apex | Sync with Salesforce.
    • Encontre seu novo S-Control na árvore de diretórios, clique nele com o botão direito do mouse e escolha Modificar remoto e publicar no servidor.
    • Se você não encontrar o S-Control, talvez o Apex Toolkit já tenha feito o upload para você, mas é recomendável usar a perspectiva de sincronização para garantir que o código mais recente seja executado no servidor.
  2. Use a IU do Salesforce.com para definir um botão que vai invocar este S-Control:
    • No menu "Configuração do app", clique em Personalizar | Contatos | Botões e links.
    • Na seção "Botões e links personalizados", clique em Novo.
    • Insira Export to Google no rótulo e mantenha Export_to_Google como o nome.
    • Escolha "Botão de lista" como o tipo de exibição.
    • Escolha "Controle S personalizado" como origem do conteúdo.
    • Escolha "Exibir em janela existente com barra lateral" como o "Comportamento".
    • Selecione "export_contacts" no menu "Controles S personalizados".
  3. Adicione o botão à lista de contatos:
    • No menu "Configuração do app", clique em Personalizar | Contatos | Layouts da pesquisa.
    • Clique em Editar na linha "Visualização da lista de contatos".
    • Destaque "Exportar para o Google" e clique na seta para a direita (>) para adicionar o botão.
    • Clique em Salvar.
  4. Faça um teste:
    • Clique na guia Contatos.
    • Selecione "Todos os contatos" como a visualização e clique em Ir.
    • Clique no botão brilhante Exportar para o Google.
    • Assista a "waiting_dots", mas não espere mais nada.

Interação com as Planilhas do Google

Se você observar a origem do mashup do Google Agenda, verá que o arquivo gcal_snippet.scf contém uma abstração para um servidor do Google Agenda. Para interagir com as Planilhas do Google, crie um arquivo semelhante para um servidor das Planilhas do Google. Reutilizei o código de Ron Hess para usar o proxy AJAX do Salesforce.com e fazer a autenticação com Google tmp, e substituí a função que grava eventos no Google Agenda por uma que grava informações nas Planilhas Google. A fonte completa desse arquivo está disponível em gspreadsheet_snippet.scf.

Em seguida, adicionei JavaScript ao S-Control export_contacts.scf para consultar informações de contato no Salesforce.com e gravá-las em uma planilha do Google. É fácil extrair dados do Salesforce.com. Basta criar uma consulta e fornecer uma função de callback para ser executada quando os dados forem retornados. Exemplo:

  var query = 'Select FirstName, LastName, Phone From Contact';
  var queryResult = sforce.connection.query(query, queryCallback);

Quando tiver os dados de contato do Salesforce.com, você precisará descobrir para onde exportá-los. No protocolo de dados RESTful do Google, cada planilha pode ser identificada por um URL exclusivo. Para ver a lista das planilhas de um usuário (e dos URLs associados), consulte o URL do metafeed: http://spreadsheets.google.com/feeds/spreadsheets/private/full. O método a seguir faz a iteração dessas planilhas, procurando uma planilha com um título específico. Quando encontra a planilha correta, ele primeiro acessa a lista de planilhas e, em seguida, retorna o URL do feed de células da primeira planilha.

function getCellFeedUrl() {
  var SPREADSHEET_TITLE = 'Salesforce.com Contacts';
  var WORKSHEET_REL = 'http://schemas.google.com/spreadsheets/2006#worksheetsfeed';
  var CELLSFEED_REL = 'http://schemas.google.com/spreadsheets/2006#cellsfeed';

  // Query to find the spreadheet called "Salesforce.com Contacts"
  var spreadsheets = g.getFeed('http://spreadsheets.google.com/feeds/spreadsheets/private/full');
  var entries = g.getEntryList(spreadsheets);
  for (var e in entries) {
    if (g.getTitle(entries[e]) == SPREADSHEET_TITLE) {
      var worksheetsFeedUrl = g.link(entries[e],WORKSHEET_REL);
      var worksheets = g.getFeed(worksheetsFeedUrl);
      var worksheetEntries = g.getEntryList(worksheets);
      return g.link(worksheetEntries[0], CELLSFEED_REL);
    }
  }
}

Mais informações sobre os feeds disponíveis na API de dados das Planilhas Google podem ser encontradas no Guia de referência.

A função queryCallback usa o método getCellFeedUrl para encontrar o URL de feed de células necessário para enviar solicitações de atualização de células e, em seguida, grava os dados de contato em uma célula de cada vez.

function queryCallback(queryResult) {
  var cellFeedUrl = getCellFeedUrl();
  var contacts = queryResult.getArray('records');
  for (var i=0; i<contacts.length; i++) {
    g.updateCell(cellFeedUrl, i+1, 1, contacts[i].LastName + ", " + contacts[i].FirstName);
    g.updateCell(cellFeedUrl, i+1, 2, contacts[i].Phone);
  }
  
  jumpback(); // Return to the contacts page when your done
}

O método updateCell existe no S-Control gspreadsheet_snippet.scf. O método recebe o URL de edição da célula na linha e coluna fornecidas e, em seguida, envia uma mensagem HTTP PUT que contém a representação de dados do Google da célula atualizada:

GoogleSpreadsheet.prototype.updateCell = function(cellsFeedUrl, row, column, content ) {
  var cellEntry = this.getFeed(cellsFeedUrl+'/R'+row+'C'+column);
  var cellEditUrl = this.link(cellEntry,'edit');

  var newCellEntry = "<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'>" +
      "<atom:category scheme='http://schemas.google.com/spreadsheets/2006' " +
      "term='http://schemas.google.com/spreadsheets/2006#cell' />" +
      "<gs:cell xmlns:gs='http://schemas.google.com/spreadsheets/2006' " +
      "row='" + row + "' col='" + column + "' inputValue='" + content + "' />" +
      "</atom:entry>";

  this.putEntry(cellEditUrl, newCellEntry);
}

Mais informações sobre como atualizar células com a API de dados do Planilhas Google podem ser encontradas no Guia do desenvolvedor.

A API de dados das Planilhas do Google usa o subdomínio https://spreadsheets.google.com para que o código acima funcione, e você precisa configurar o servidor proxy AJAX do Salesforce.com e adicionar https://spreadsheets.google.com.

Você também precisa acessar o Documentos Google e criar uma nova planilha para armazenar os dados. Salve-o como Contatos do Salesforce.com.

Depois de fazer upload desses S-Controls, você poderá exportar seus dados de contato para uma planilha do Google. E da outra forma? Com seus novos conhecimentos sobre o Salesforce.com e as APIs de dados do Google, você também pode escrever códigos para importar dados de contato do Planilhas Google para o Salesforce.com.

Conclusão

Este artigo é um pouco difícil, mas agora que você já conhece a plataforma Salesforce.com e as APIs de dados do Google, pense em todos os aplicativos que pode criar para aproveitar esses sistemas poderosos. A família de APIs do Google Data está sempre crescendo, expondo mais informações para você aproveitar nos seus aplicativos. A plataforma Salesforce.com oferece muitas ferramentas úteis que não foram abordadas neste artigo. Vou procurar seu próximo mashup corporativo no App Exchange.

Divirta-se com os códigos!

Recursos