Melhorar desempenho

Este documento aborda algumas técnicas que podem ser usadas para melhorar o desempenho do aplicativo. Em alguns casos, exemplos de outras APIs implementadas são usados para ilustrar as ideias apresentadas. No entanto, os mesmos conceitos são aplicáveis à API Display & Video 360.

Como trabalhar com recursos parciais

Outra maneira de melhorar o desempenho das suas chamadas de API é solicitar apenas a parte dos dados na qual você tem interesse. Isso permite que o aplicativo evite transferir, analisar e armazenar campos desnecessários para que recursos como rede, CPU e memória sejam usados de maneira mais eficiente.

Resposta parcial

Por padrão, depois de processar as solicitações, o servidor envia de volta a representação completa de um recurso. Para melhorar o desempenho, solicite ao servidor o envio apenas dos campos realmente necessários para receber uma resposta parcial.

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

Exemplo

O exemplo a seguir mostra o uso do parâmetro fields com a API Display & Video 360.

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

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1

Resposta de recursos completos:os dados de recursos completos incluem os campos a seguir, além de muitos outros omitidos para agilizar o processo.

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

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

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

Resposta parcial:em resposta à solicitação acima, o servidor envia de volta uma resposta que contém uma matriz de anunciantes simplificada que inclui apenas o ID do anunciante, o nome de exibição e a propriedade do ID do parceiro de cada anunciante, se estiverem presentes.

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

A resposta é um objeto JSON que inclui apenas os campos selecionados e os respectivos objetos pais.

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

Resumo da sintaxe do parâmetro "Campos"

O formato do valor do parâmetro de solicitação fields baseia-se vagamente na sintaxe XPath. Confira abaixo um resumo da sintaxe compatível e outros exemplos fornecidos na seção a seguir.

• 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.

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

  Por exemplo: fields=advertisers(advertiserId,generalConfig/domainUrl) retorna apenas o ID do anunciante e o URL do domínio para cada elemento na matriz de anunciantes. Também é possível especificar um único subcampo, em que fields=advertisers(advertiserId) é equivalente a fields=advertisers/advertiserId.

Mais exemplos do uso do parâmetro fields

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

Observação: assim como com todos os valores de parâmetro de consulta, o valor do parâmetro fields precisa ter codificação de URL. Para facilitar a leitura, os exemplos neste documento estão sem a codificação.

Identifique os campos a serem retornados ou faça seleções de campos.

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

Veja alguns exemplos do nível de coleção:

Exemplo	Efeito
advertisers	Retorna todos os elementos da matriz advertisers, incluindo todos os campos em cada elemento, mas nenhum outro campo.
advertisers,nextPageToken	Retorna o campo nextPageToken e todos os elementos na matriz advertisers.
advertisers/advertiserId	Retorna apenas o advertiserId para todos os elementos da matriz advertisers. Sempre que um campo aninhado é retornado, a resposta inclui os objetos pais incluídos. Os campos pais não incluem outros campos filhos, a menos que eles também sejam selecionados explicitamente.
advertisers/generalConfig/domainUrl	Retorna o campo domainUrl para o objeto generalConfig, que está aninhado na matriz advertisers.

Veja alguns exemplos com base no recurso:

Exemplo	Efeito
advertiserId	Retorna o campo advertiserId do recurso solicitado.
generalConfig/domainUrl	Retorna o campo domainUrl do objeto generalConfig no recurso solicitado.

Solicite apenas partes de campos específicos usando subseleções.

Por padrão, se houver campos específicos especificados na solicitação, o servidor vai retornar os objetos ou elementos da matriz por completo. É possível especificar uma resposta que inclua apenas alguns subcampos. Para fazer isso, use a sintaxe de subseleção ( ), como no exemplo abaixo.

Exemplo	Efeito
advertisers(advertiserId,generalConfig/domainUrl)	Retorna apenas os valores de advertiserId e generalConfig domainUrl para cada elemento na matriz advertisers.

Como processar respostas parciais

Depois que o servidor processar uma solicitação válida que inclua o parâmetro de consulta fields, ele vai enviar de volta um código de status HTTP 200 OK, além dos dados solicitados. Se o parâmetro de consulta fields tiver um erro ou for inválido, o servidor vai retornar um código de status HTTP 400 Bad Request com uma mensagem de erro informando o que havia de errado com a seleção de campos (por exemplo, "Invalid field selection a/b").

Observação: em 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 gerenciável. Caso contrário, os ganhos de desempenho possíveis com a resposta parcial não serão alcançados.