Dicas de desempenho

Este documento abrange algumas técnicas que podem ser usadas para melhorar o desempenho do seu aplicativo. Em alguns casos, exemplos de outras APIs ou APIs genéricas são usados para ilustrar as ideias apresentadas. No entanto, os mesmos conceitos se aplicam à Google Analytics API.

Uso de gzip

Um jeito fácil e conveniente de reduzir a largura de banda necessária para cada solicitação é ativar a compactação gzip. Embora isso exija tempo adicional de CPU para descompactar os resultados, a relação com os custos de rede geralmente é vantajosa.

Para receber uma resposta codificada em gzip, é necessário fazer duas coisas: definir um cabeçalho Accept-Encoding e modificar seu user-agent para que tenha a string gzip. Veja um exemplo de cabeçalhos HTTP devidamente formados para permitir a compactação em gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Trabalho com recursos parciais

Outra maneira de melhorar o desempenho das suas chamadas de API é solicitando apenas a parte dos dados na qual você tem interesse. Isso permite que o aplicativo evite a transferência, a análise e o armazenamento de campos desnecessários. Dessa forma, o aplicativo utiliza recursos, incluindo rede, CPU e memória, de forma mais eficiente.

Resposta parcial

Por padrão, o servidor retorna a representação completa de um recurso após processar as solicitações. Para um melhor desempenho, é possível pedir ao servidor para enviar somente os campos que você realmente precisa e, em vez disso, receber uma resposta parcial.

Para solicitar uma resposta parcial, use o parâmetro de solicitação fields para especificar os campos que devem ser retornados. Use esse parâmetro com qualquer solicitação que retorne dados de resposta.

Exemplo

O exemplo a seguir mostra o uso de parâmetros fields com uma API "de demonstração" genérica (fictícia).

Solicitação simples: essa solicitação GET HTTP omite o parâmetro fields e retorna todo o recurso.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

Resposta de recurso completo: os dados de recurso completo incluem os seguintes campos, juntamente com muitos outros que foram omitidos para fins de resumo.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Solicitação para uma resposta parcial: a solicitação a seguir para esse mesmo recurso usa o parâmetro fields para reduzir significativamente o volume de dados retornados.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

Resposta parcial: para a solicitação acima, o servidor retorna uma resposta que contém somente o tipo de informação, junto com uma matriz reduzida de itens, que inclui só informações do título HTML e características de comprimento em cada item.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

A resposta é um objeto JSON que traz somente os campos selecionados e os objetos pai deles que estão incluídos.

Veja detalhes sobre como formatar o parâmetro fields e mais informações sobre o que exatamente é retornado na resposta.

Resumo da sintaxe do parâmetro fields

O formato do valor do parâmetro de solicitação fields é vagamente baseado na sintaxe XPath. A sintaxe compatível é resumida a seguir, e os exemplos adicionais são fornecidos na seção seguinte.

Use uma lista separada por vírgulas para selecionar diversos campos.
Use a/b para selecionar um campo b que está aninhado dentro do campo a, use a/b/c para selecionar um campo c aninhado dentro de b.

Exceção: para respostas da API que usam wrappers "data", em que a resposta é aninhada dentro de um objeto data que se parece com data: { … }, não incluir "data" na especificação fields. A inclusão de um objeto de dados com uma especificação de campos como data/a/b gera um erro. Em vez disso, use a especificação fields, como a/b.
Use um subseletor para solicitar um conjunto de subcampos específicos de matrizes ou objetos, colocando as expressões entre parênteses "( )".
Por exemplo: fields=items(id,author/email) retorna apenas o ID do item e o e-mail do autor para cada elemento da matriz de itens. Você também pode especificar um único subcampo, em que fields=items(id) é equivalente a fields=items/id.
Use caracteres coringa em seleções de campo, se necessário.
Por exemplo: fields=items/pagemap/* seleciona todos os objetos em um mapa de página.

Mais exemplos de utilização do parâmetro fields

Os exemplos abaixo incluem descrições de como o valor do parâmetro fields afeta a resposta.

Observação: tal como acontece com todos os valores de parâmetro de consulta, o valor do parâmetro fields deve ser codificado como URL. Para facilitar a leitura, os exemplos deste documento omitem a codificação.

Identifique os campos que quer retornar ou faça seleções de campo.

O valor do parâmetro de solicitação fields é uma lista de campos separados por vírgulas em que cada campo é especificado em relação à raiz da resposta. Assim, se você executar uma operação de lista, a resposta é um conjunto e geralmente inclui uma matriz de recursos. Se você executar uma operação que retorna um único recurso, os campos serão especificados em relação a esse recurso. Se o campo selecionado for (ou fizer parte de) uma matriz, o servidor retornará a parte selecionada de todos os elementos na matriz.

Veja alguns exemplos no nível da coleção:

Exemplos	Efeito
`items`	Retorna todos os elementos na matriz de itens, incluindo todos os campos em cada elemento, mas não outros campos.
`etag,items`	Retorna o campo `etag` e todos os elementos na matriz de itens.
`items/title`	Retorna somente o campo `title` para todos os elementos na matriz de itens. Sempre que um campo aninhado é retornado, a resposta inclui os objetos pai incluídos. Os campos pai não incluem campos filho, a menos que eles também sejam selecionados de forma explícita.
`context/facets/label`	Retorna somente o campo `label` para todos os membros da matriz `facets`, que está aninhada sob o objeto `context`.
`items/pagemap/*/title`	Para cada elemento na matriz de itens, retorna apenas o campo `title` (se presente) de todos os objetos que são filhos de `pagemap`.

Veja alguns exemplos no nível do recurso:

Exemplos	Efeito
`title`	Retorna o campo `title` do recurso solicitado.
`author/uri`	Retorna o subcampo `uri` do objeto `author` do recurso solicitado.
`links/*/href`	Retorna o campo `href` de todos os objetos que são filhos de `links`.

Solicite somente partes de campos determinados usando subseleções.

Por padrão, se sua solicitação especifica determinados campos, o servidor retorna os objetos ou elementos de matriz por completo. Você pode especificar uma resposta que inclui apenas alguns subcampos. Você pode fazer isso usando a sintaxe de subseleção "( )", como no exemplo abaixo.

Exemplo	Efeito
`items(title,author/uri)`	Retorna apenas os valores do `title` e do `uri` do autor para cada elemento da matriz de itens.

Como tratar respostas parciais

Depois que um servidor processa uma solicitação válida que inclui o parâmetro de consulta fields, ele envia de volta um código de status HTTP 200 OK, juntamente com os dados solicitados. Se o parâmetro de consulta fields tem um erro ou é inválido, o servidor retorna um código de status HTTP 400 Bad Request, com uma mensagem de erro informando o usuário sobre o erro em sua seleção de campos. Por exemplo, "Invalid field selection a/b".

Veja o exemplo da resposta parcial apresentado na seção introdutória acima. A seleção utiliza o parâmetro fields para determinar quais campos serão retornados.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

A resposta parcial tem esta aparência:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Observação: para APIs compatíveis com parâmetros de consulta para paginação de dados (maxResults e nextPageToken, por exemplo), use esses parâmetros para reduzir os resultados de cada consulta a um tamanho administrável. Caso contrário, talvez não haja melhorias de desempenho.