Melhore o desempenho

Este documento aborda algumas técnicas que pode usar para melhorar o desempenho da sua aplicação. Em alguns casos, são usados exemplos de outras APIs ou APIs genéricas para ilustrar as ideias apresentadas. No entanto, os mesmos conceitos são aplicáveis à API Resource Manager.

Compressão com gzip

Uma forma fácil e conveniente de reduzir a largura de banda necessária para cada pedido é ativar a compressão gzip. Embora isto exija tempo adicional da CPU para descomprimir os resultados, a compensação com os custos de rede torna-o geralmente muito vantajoso.

Para receber uma resposta com codificação gzip, tem de fazer duas coisas: definir um cabeçalho Accept-Encoding e modificar o seu agente do utilizador para conter a string gzip. Segue-se um exemplo de cabeçalhos HTTP corretamente formados para ativar a compressão gzip:

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

Trabalhar com recursos parciais

Outra forma de melhorar o desempenho das suas chamadas API é pedir apenas a parte dos dados que lhe interessa. Isto permite que a sua aplicação evite transferir, analisar e armazenar campos desnecessários, para que possa usar recursos, incluindo rede, CPU e memória, de forma mais eficiente.

Resposta parcial

Por predefinição, o servidor envia de volta a representação completa de um recurso após o processamento de pedidos. Para um melhor desempenho, pode pedir ao servidor que envie apenas os campos de que realmente precisa e, em alternativa, receber uma resposta parcial.

Para pedir uma resposta parcial, use o parâmetro de pedido fields para especificar os campos que quer que sejam devolvidos. Pode usar este parâmetro com qualquer pedido que devolva dados de resposta.

Exemplo

O exemplo seguinte mostra a utilização do parâmetro fields com uma API "Demo" genérica (fictícia).

Pedido simples: este pedido HTTP GET omite o parâmetro fields e devolve o recurso completo.

https://www.googleapis.com/demo/v1

Resposta de recurso completa: os dados de recursos completos incluem os seguintes campos, juntamente com muitos outros que foram omitidos para simplificar.

{
  "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",
    ...
  },
  ...
  ]
}

Pedido de uma resposta parcial: o seguinte pedido deste mesmo recurso usa o parâmetro fields para reduzir significativamente a quantidade de dados devolvidos.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Resposta parcial: em resposta ao pedido acima, o servidor envia uma resposta que contém apenas as informações do tipo, juntamente com uma matriz de itens reduzida que inclui apenas o título HTML e as informações das características de comprimento em cada item.

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

Tenha em atenção que a resposta é um objeto JSON que inclui apenas os campos selecionados e os respetivos objetos principais circundantes.

Os detalhes sobre como formatar o parâmetro fields são abordados a seguir, seguidos de mais detalhes sobre o que é exatamente devolvido na resposta.

Resumo da sintaxe do parâmetro fields

O formato do valor do parâmetro de pedido fields baseia-se vagamente na sintaxe XPath. A sintaxe suportada é resumida abaixo e são fornecidos exemplos adicionais na secção seguinte.

  • Use uma lista separada por vírgulas para selecionar vários campos.
  • Use a/b para selecionar um campo b aninhado no campo a; use a/b/c para selecionar um campo c aninhado em b.

    Exceção: para respostas da API que usam wrappers "data", em que a resposta está aninhada num objeto data com o aspeto de data: { ... }, não inclua "data" na especificação fields. A inclusão do objeto de dados com uma especificação de campos como data/a/b causa um erro. Em alternativa, use apenas uma especificação fields, como a/b.

  • Use um subseletor para pedir um conjunto de subcampos específicos de matrizes ou objetos colocando expressões entre parênteses "( )".

    Por exemplo: fields=items(id,author/email) devolve apenas o ID do artigo e o email do autor para cada elemento na matriz de artigos. Também pode especificar um único subcampo, em que fields=items(id) é equivalente a fields=items/id.

  • Se necessário, use carateres universais nas seleções de campos.

    Por exemplo: fields=items/pagemap/* seleciona todos os objetos num mapa de páginas.

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.

Nota: tal como acontece com todos os valores dos parâmetros de consulta, o valor do parâmetro fields tem de ser codificado por URL. Para uma melhor legibilidade, os exemplos neste documento omitem a codificação.

Identifique os campos que quer que sejam devolvidos ou faça seleções de campos.
O valor do parâmetro de pedido fields é uma lista de campos separados por vírgulas, e cada campo é especificado relativamente à raiz da resposta. Assim, se estiver a realizar uma operação de list, a resposta é uma coleção e, geralmente, inclui uma matriz de recursos. Se estiver a realizar uma operação que devolve um único recurso, os campos são especificados relativamente a esse recurso. Se o campo que selecionar for (ou fizer parte de) uma matriz, o servidor devolve a parte selecionada de todos os elementos na matriz.

Seguem-se alguns exemplos ao nível da recolha:
Exemplos Efeito
items Devolve todos os elementos na matriz de itens, incluindo todos os campos em cada elemento, mas nenhum outro campo.
etag,items Devolve o campo etag e todos os elementos na matriz de artigos.
items/title Devolve apenas o campo title para todos os elementos na matriz de artigos.

Sempre que é devolvido um campo aninhado, a resposta inclui os objetos principais circundantes. Os campos principais não incluem outros campos secundários, a menos que também sejam selecionados explicitamente.
context/facets/label Devolve apenas o campo label para todos os membros da matriz facets, que está aninhada no objeto context.
items/pagemap/*/title Para cada elemento na matriz de itens, devolve apenas o campo title (se presente) de todos os objetos que são filhos de pagemap.

Seguem-se alguns exemplos ao nível do recurso:
Exemplos Efeito
title Devolve o campo title do recurso pedido.
author/uri Devolve o subcampo uri do objeto author no recurso pedido.
links/*/href
 Devolve o campo href de todos os objetos que são filhos de links.
Pedir apenas partes de campos específicos através de subseleções.
Por predefinição, se o seu pedido especificar campos específicos, o servidor devolve os objetos ou os elementos da matriz na sua totalidade. Pode especificar uma resposta que inclua apenas determinados subcampos. Pode fazê-lo através da sintaxe de subseleção "( )", como no exemplo abaixo.
Exemplo Efeito
items(title,author/uri) Devolve apenas os valores de title e uri do autor para cada elemento na matriz de artigos.

Processamento de respostas parciais

Depois de um servidor processar um pedido válido que inclua o parâmetro de consulta fields, envia um código de estado HTTP 200 OK, juntamente com os dados pedidos. Se o parâmetro de consulta fields tiver um erro ou for inválido de outra forma, o servidor devolve um código de estado HTTP 400 Bad Request, juntamente com uma mensagem de erro a indicar ao utilizador o que estava errado com a seleção de campos (por exemplo, "Invalid field selection a/b").

Segue-se o exemplo de resposta parcial apresentado na secção introdutória acima. O pedido usa o parâmetro fields para especificar os campos a devolver.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

A resposta parcial tem o seguinte aspeto:

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

Nota: para APIs que suportam parâmetros de consulta para paginação de dados (por exemplo, maxResults e nextPageToken), use esses parâmetros para reduzir os resultados de cada consulta a um tamanho gerível. Caso contrário, os ganhos de desempenho possíveis com a resposta parcial podem não ser realizados.