Atualizar um rótulo

É possível atualizar um único rótulo aplicando um conjunto de solicitações de atualização que resultam em uma nova revisão de rascunho. Por exemplo, é possível atualizar uma propriedade de rótulo (a descrição do rótulo) ou adicionar um novo Field ao rótulo.

A atualização de rótulos funciona como uma atualização em lote, já que o método usa uma lista de objetos de atualização Request. Ele faz atualizações de acordo com a mesma ordem especificada na solicitação em lote. As atualizações no lote são aplicadas atomicamente. Ou seja, se uma solicitação no lote não for concluída, toda a atualização vai falhar, e nenhuma das mudanças (potencialmente dependentes) será aplicada. O rótulo permanece inalterado.

Se a atualização for bem-sucedida, a revisão do rascunho resultante precisará ser publicada antes que as mudanças possam ser usadas com qualquer item do Drive.

Atualizar objetos de rótulo

Um rótulo inclui muitos outros tipos de objetos que podem ser atualizados, como:

• Propriedades do rótulo
• Campos e tipos de campos
• Opções de seleção e propriedades de opções de seleção

Estes são alguns dos muitos objetos que controlam a aparência e a operação de um rótulo.

Categorias de operação

As seguintes operações compatíveis com o método labels.delta podem ser agrupadas nas seguintes categorias gerais:

Categoria	Descrição
Criar	Adicione objetos.
Atualizar	Atualize determinadas propriedades de um objeto.
Ativar	Ative os objetos.
Desativar	Desativar objetos.
Excluir	Remover objetos.

Essas categorias são usadas na próxima seção para descrever o comportamento de operações específicas.

Solicitações de atualização

O método labels.delta funciona recebendo um ou mais objetos Request, cada um especificando um único tipo de solicitação a ser executada. Há muitos tipos diferentes de solicitações. Confira uma análise dos tipos de solicitações, agrupadas em diferentes categorias.

Tipo de solicitação
Propriedades do rótulo	Atualizar UpdateLabelPropertiesRequest
Campo	Criar CreateFieldRequest Atualizar UpdateFieldPropertiesRequest UpdateFieldTypeRequest Ativar EnableFieldRequest Desativar DisableFieldRequest Excluir DeleteFieldRequest
Opção de seleção	Criar CreateSelectionChoiceRequest Atualizar UpdateSelectionChoicePropertiesRequest Ativar EnableSelectionChoiceRequest Desativar DisableSelectionChoiceRequest Excluir DeleteSelectionChoiceRequest

Máscaras de campo

Muitas das solicitações do tipo "Atualizar" e "Desativar" exigem um FieldMask. É uma lista delimitada por vírgulas de campos que você quer atualizar sem alterar os outros. A máscara é necessária para garantir que apenas os campos que você quer editar sejam atualizados. É preciso especificar pelo menos um campo.

Uma máscara de campo de * é tratada como um caractere curinga e é uma abreviação para especificar todos os campos em uma mensagem. A sintaxe de caractere curinga pode gerar resultados indesejados, já que um campo pode reverter ao estado padrão se você não especificar um valor para ele na solicitação de atualização. Para aplicativos de produção, sempre liste os campos específicos que estão sendo atualizados em máscaras de campo e evite usar caracteres curinga *.

Exemplo

Para atualizar um rótulo, use o método delta na coleção labels.

Você também precisa especificar:

• useAdminAccess é true para usar as credenciais de administrador do usuário. O servidor verifica se o usuário é um administrador do marcador antes de permitir o acesso.

• Um Request que especifica as atualizações aplicáveis ao rótulo.

• Um rótulo title usando o método property.

• Um ou mais Field.

• Um recurso de rótulo que representa todos os rótulos. Ele contém um recurso Name e ID, que é um identificador globalmente exclusivo do rótulo.

• LabelView é LABEL_VIEW_FULL para definir a visualização de recursos aplicada às respostas de rótulo. LABEL_VIEW_FULL retorna todos os campos possíveis.

Neste exemplo, usamos o ID para atualizar o rótulo correto.

Python

body = {
'use_admin_access': True,
'requests': [{
  'update_label': {
    'properties': {
      'title': 'TITLE'
    },
    'update_mask': {
      'paths': ['title']
    }
  },
}, {
  'create_field': {
    'field': {
      'properties': {
        'display_name': 'DISPLAY_NAME'
      },
      'text_options': {}
    }
  }
}],
'view': 'LABEL_VIEW_FULL'
}
response = service.labels().delta(
  body=body,
  name='labels/ID').execute()

Node.js

var body = {
  'use_admin_access': true,
  'requests': [{
    'update_label': {
      'properties': {
        'title': 'TITLE'
      },
      'update_mask': {
        'paths': ['title']
      }
    },
  }, {
    'create_field': {
      'field': {
        'properties': {
          'display_name': 'DISPLAY_NAME'
        },
        'text_options': {}
      }
    }
  }],
  'view': 'LABEL_VIEW_FULL'
};
service.labels.delta({
  'resource': body,
  'name': 'labels/ID'
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

O rótulo, o campo ou a opção são atualizados, o ID de revisão do rótulo é incrementado e o rótulo é armazenado em um banco de dados como um rascunho. O marcador tem o State de PUBLISHED com hasUnpublishedChanges=true, o que significa que há mudanças no rascunho, mas elas não estão disponíveis para os usuários. O rótulo atualizado precisa ser PUBLISHED para que as mudanças fiquem visíveis aos usuários. Para mais informações, consulte Ciclo de vida do rótulo.