Implementação: respostas parciais

Os exemplos a seguir mostram como recuperar respostas parciais da API na API YouTube Data (v3).

Observação: o guia Primeiros passos da API fornece mais detalhes sobre solicitações e respostas parciais.

A API v3 permite e realmente exige a recuperação de recursos parciais para que os aplicativos evitem transferir, analisar e armazenar dados desnecessários. Esta abordagem também garante que a API use a rede, a CPU e os recursos da memória de modo mais eficiente.

A API é compatível com dois parâmetros de solicitação, part e fields, que permitem identificar as propriedades de recurso que precisam ser incluídas nas respostas da API. O parâmetro part também identifica as propriedades que precisam ser definidas por solicitações de API que inserem ou atualizam recursos.

Se uma solicitação de atualização não especificar um valor para uma propriedade de recurso que já tinha um valor, o valor existente será excluído se as seguintes condições forem verdadeiras:

• O valor da propriedade pode ser modificado pela solicitação. Por exemplo, ao atualizar um recurso video, é possível atualizar o valor da propriedade snippet.description, mas não o valor do objeto snippet.thumbnails.

• O valor do parâmetro part da solicitação identifica a parte do recurso que contém a propriedade.

Exemplo

Por exemplo, suponha que você queira atualizar o recurso video mostrado abaixo. Todas as propriedades mostradas abaixo podem ser atualizadas pela API, e as propriedades dos recursos não relevantes para o exemplo foram omitidas.

{
  "snippet": {
    "title": "Old video title",
    "description": "Old video description",
    "tags": ["keyword1","keyword2","keyword3"],
    "categoryId: 22
  },
  "status": {
    "privacyStatus": "private",
    "publishAt": "2014-09-01T12:00:00.0Z",
    "license": "youtube",
    "embeddable": True,
    "publicStatsViewable": True
  }
}

Você chama o método videos.update e define o valor do parâmetro part como snippet. O corpo da solicitação de API contém o seguinte recurso:

{
  "snippet": {
    "title": "New video title",
    "tags": ["keyword1","keyword2","keyword3"],
    "categoryId: 22
  }
}

Essa solicitação atualiza o título do vídeo, exclui a descrição e não muda as tags ou o ID da categoria. A descrição do vídeo foi excluída porque a solicitação não especifica um valor para a propriedade snippet.description.

As propriedades no objeto status não são afetadas porque o valor do parâmetro part não incluiu status como uma das partes que a solicitação atualizaria. Na verdade, se o corpo da solicitação de API incluísse o objeto status, a API retornaria uma resposta HTTP 400 (Bad Request) devido a uma parte inesperada incluída no corpo da solicitação.