更新標籤

您可以套用一組更新要求來產生新的草稿修訂版本，藉此更新單一標籤。舉例來說，您可以更新現有標籤屬性 (標籤說明)，也可以在標籤中加入新的 Field。

標籤更新可像批次更新一樣進行，因為此方法會取得更新 Request 物件的清單。該物件會根據批次要求中指定的順序進行更新。系統會以不可分割的形式套用批次更新中的更新。也就是說，如果批次中的任何要求失敗，則整個更新都會失敗，且不會套用任何 (可能相依) 的變更。標籤未變更。

如果更新成功，就必須先發布產生的草稿修訂版本，變更才能搭配任何雲端硬碟項目使用。

更新標籤物件

標籤包含許多其他可更新的物件類型，例如：

  • 標籤屬性
  • 欄位與欄位類型
  • 選擇與選項屬性

這些是控制標籤外觀與作業的許多物件。

作業類別

labels.delta 方法支援的下列作業可分為以下廣泛類別：

類別 說明
建立新增物件。
更新更新物件的特定屬性。
啟用啟用物件。
停用停用物件。
刪除移除物件。

下節會使用這些類別，說明特定作業的行為。

更新要求

labels.delta 方法的運作原理是取用一或多個 Request 物件，每個物件會指定執行單一類型的要求。要求有多種類型以下分析要求類型，並分為不同類別。

要求類型
標籤屬性
更新 UpdateLabelPropertiesRequest
欄位
建立 CreateFieldRequest
更新 UpdateFieldPropertiesRequest
UpdateFieldTypeRequest
啟用 EnableFieldRequest
停用 DisableFieldRequest
刪除 DeleteFieldRequest
選項
建立 CreateSelectionChoiceRequest
更新 UpdateSelectionChoicePropertiesRequest
啟用 EnableSelectionChoiceRequest
停用 DisableSelectionChoiceRequest
刪除 DeleteSelectionChoiceRequest

欄位遮罩

許多「更新」和「停用」類型要求都需要 FieldMask。這是要更新的欄位清單 (以半形逗號分隔)，其他欄位則保持不變。您需要遮罩以確保只有要編輯的欄位會更新。您必須指定至少一個欄位。

範例

如要更新標籤，請針對 labels 集合使用 delta 方法。

您還必須指定：

  • useAdminAccess：true，以便使用使用者的管理員憑證。伺服器會先驗證使用者是標籤管理員，再授予存取權。

  • Request，用於指定標籤適用的更新。

  • 透過 property 方法提供的標籤 title。

  • 一或多個「Field」。

  • 代表每個標籤的標籤資源。其中包含資源 Name 和 ID，這是標籤的全域專屬 ID。

  • LabelView 為 LABEL_VIEW_FULL，可設定套用至標籤回應的資源檢視畫面。LABEL_VIEW_FULL 會傳回所有可能的欄位。

這個範例使用 ID 更新正確的標籤。

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);
});

標籤、欄位或選項會更新、標籤的修訂版本 ID 會遞增，並將標籤以草稿標籤儲存在資料庫中。標籤包含 PUBLISHED 的 State，其中 hasUnpublishedChanges=true 代表有草稿變更，但使用者無法取得。更新後的標籤必須是 PUBLISHED，使用者才會看到變更。詳情請參閱「標籤生命週期」一文。