REST para o caixeiro viajante: usando dados do Google no Salesforce.com

Lane LiaBraaten, Programas para desenvolvedores do Google
Novembro de 2007

Introdução

A Salesforce.com e o Google hospedam aplicativos populares de "software como serviço", e ambas as organizações fornecem APIs que permitem aos desenvolvedores acessar os grandes armazenamentos de dados que alimentam esses aplicativos. 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 empresarial, e o Salesforce.com criou uma plataforma extensa para criar aplicativos comerciais personalizados. Assim, há muitas oportunidades para os desenvolvedores (você!) combinarem o poder do Google e do Salesforce.com.

Neste artigo, mostramos como usar as APIs de dados do Google RESTful 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 Salesforce.com e do Google e escrever o seu próprio.

Olá, Salesforce.com!

Se você for um iniciante no Salesforce.com como eu, comece inscrevendo-se 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.

Em seguida, instale o Apex Toolkit para Eclipse. O kit de ferramentas requer Java 1.5 e Eclipse 3.2.2 ou versões mais recentes. Se você conhece o Eclipse, o site de atualização de software do kit de ferramentas é http://www.adnsandbox.com/eclipsetoolkit/10.0/. Se você não conhece os plug-ins do Eclipse ou algo der errado durante a instalação, a wiki do Apex inclui instruções detalhadas de instalação.

Depois que o conjunto de ferramentas for instalado, você poderá acessar o conteúdo de ajuda do Apex integrado ao sistema de ajuda do Eclipse. No Eclipse, acesse Ajuda | Conteúdo da ajuda | Apex Toolkit para Eclipse para ver esse conteúdo. Um dos recursos de ajuda é um tutorial de início rápido que mostra como criar um projeto e adicionar controles S, classes e gatilhos. Se você nunca trabalhou com código Apex, siga este tutorial e crie um projeto Apex antes de continuar.

Exportar eventos para o Google Agenda

Ron Hess escreveu um aplicativo Google Calendar Mash-up que permite exportar eventos do Salesforce.com para o Google Agenda. Ron também escreveu um artigo que explica como o mashup dele funciona. O aplicativo Google Planilhas que vou mostrar como criar mais tarde é inspirado no mash-up do Google Agenda do Ron. Valeu, 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. No começo, precisei de uma ajudinha. Então, fiz o seguinte para ver o app do Ron em ação.

  1. Instale o aplicativo:
    • Acesse a página Google Calendar Mash-up e clique em Baixar agora.
    • Insira suas credenciais de ADN e clique em Continuar.
    • Leia os Termos e Condições e clique em Continuar.
    • Clique em Próxima na página "Examinar o conteúdo do pacote".
    • 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 de site remoto.
    • Clique em Novo site remoto.
    • Insira Google como o "Nome do site remoto" e, para o "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 da página de eventos.
    • 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 seu calendário.
    • Se você não tiver nenhum evento, clique em Novo evento para criar um.
    • Clique em um evento para abrir 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 dar ao aplicativo Salesforce acesso de gravação ao Google Agenda.
    • Ver o evento no Google Agenda

Como criar um aplicativo das Planilhas Google

Ok, você provavelmente está cansado de clicar nas páginas do Salesforce.com e pronto para escrever um código. Abra o Eclipse novamente e você vai notar que o projeto do Apex criado agora contém os S-Controls do app Google Agenda do Ron. Isso acontece porque o Apex Toolkit para Eclipse está sempre sincronizando com o Salesforce.com. Legal, né?

Você pode criar seu próprio app de dados do Google reutilizando algumas das funcionalidades do mashup do Google Agenda, como os controles de autenticação. No restante desta seção, vou mostrar como criar um app que exporta seus contatos do Salesforce.com para uma planilha Google.

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 conter qualquer tipo de conteúdo que possa ser exibido ou executado em um navegador da Web, como HTML, CSS ou JavaScript.

Há muitos componentes móveis em um mashup do Salesforce.com e do Google. Por isso, a primeira coisa que fiz foi adicionar um botão "Exportar para o Google" à página da lista de contatos que invoca um S-Control simples. Isso garante que toda a estrutura esteja correta antes de eu me aprofundar no JavaScript.

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

O novo S-Control vai conter um arquivo HTML básico. Você vai adicionar um monte de JavaScript no <head>, mas pode preencher o <body> primeiro para que haja algo a ser mostrado ao usuário enquanto os contatos são exportados. Copie este HTML no corpo do seu S-Control para mostrar os "pontos de espera" e um logotipo do Google Planilhas:

<div id="waiting" align="center" />
  <img src="/https/developers.google.com/img/icon/home32.png" height="64" width="64" />
  <img src="/https/developers.google.com/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 você pode 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 projeto do Apex e selecione Apex | Synchronize with Salesforce.
    • Encontre seu novo S-Control na árvore de diretórios, clique com o botão direito do mouse e escolha Substituir remoto e publicar no servidor.
    • Se você não encontrar seu S-Control, talvez o Apex Toolkit já tenha feito o upload dele para você. No entanto, é recomendável usar a perspectiva de sincronização para garantir que o código mais recente esteja sendo executado no servidor.
  2. Use a interface do Salesforce.com para definir um botão que vai invocar esse 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 Exportar para o Google como o 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 a origem do conteúdo.
    • Escolha "Mostrar na janela atual 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 de pesquisa.
    • Clique em Editar na linha "Visualização em 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 novo botão Exportar para o Google.
    • Assista os "waiting_dots", mas não espere mais nada acontecer.

Como interagir com as Planilhas Google

Se você analisar a origem do mashup do Google Agenda, vai notar que o arquivo gcal_snippet.scf contém uma abstração para um servidor do Google Agenda. Para interagir com as Planilhas Google, crie um arquivo semelhante para um servidor das Planilhas Google. Reutilizei o código de Ron Hess para usar o proxy AJAX do Salesforce.com e fazer a autenticação com o Google AuthSub. Além disso, 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 controle S export_contacts.scf para consultar o Salesforce.com em busca de informações de contato e gravar em uma planilha Google. É fácil extrair dados do Salesforce.com. Basta criar uma consulta e fornecer uma função de callback para executar quando os dados forem retornados. Exemplo:

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

Depois de ter as informações de contato do Salesforce.com, você precisa descobrir onde exportá-las. No protocolo RESTful Google Data, cada planilha pode ser identificada por um URL exclusivo. Para acessar a lista de planilhas de um usuário (e os URLs associados), consulte o URL do metafeed: http://spreadsheets.google.com/feeds/spreadsheets/private/full. O método a seguir faz a iteração nessas planilhas, procurando uma com um título específico. Quando ele encontra a planilha correta, primeiro recebe a lista de planilhas e depois 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);
    }
  }
}

Para mais informações sobre os feeds disponíveis na API Google Spreadsheets Data, consulte o Guia de referência.

A função queryCallback usa o método getCellFeedUrl para encontrar o URL do feed de células necessário para enviar solicitações de atualização de células e, em seguida, grava as informações de contato uma célula por 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 especificadas e 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);
}

Para mais informações sobre como atualizar células com a API Google Spreadsheets Data, consulte o Guia para desenvolvedores.

A API Google Spreadsheets Data usa o subdomínio https://spreadsheets.google.com. Portanto, antes que o código acima funcione, é necessário configurar o servidor proxy AJAX do Salesforce.com e adicionar https://spreadsheets.google.com.

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

Depois de fazer upload desses S-Controls, você poderá exportar suas informações de contato para uma planilha Google. E se for ao contrário? Com seu novo conhecimento das APIs de dados do Salesforce.com e do Google, você também pode escrever um código para importar informações de contato das Planilhas Google para o Salesforce.com.

Conclusão

Este artigo apenas arranhou a superfície, mas agora que você está por dentro da plataforma Salesforce.com e das APIs de dados do Google, pense em todos os aplicativos que pode escrever para aproveitar esses sistemas poderosos. A família de APIs de dados do Google está sempre crescendo, expondo mais informações para você aproveitar nos seus aplicativos, e a plataforma Salesforce.com oferece muitas ferramentas úteis que não foram abordadas neste artigo. Vou procurar seu próximo mashup empresarial na AppExchange.

Divirta-se com os códigos!

Recursos