如何在Google Apps Script中为Person添加userDefined字段？附实现代码

问题场景 #

尝试通过Google People API的userDefined字段存储联系人ID编号时，仅当联系人已在Contacts应用中添加过自定义字段时脚本才能成功执行；若联系人无自定义字段，执行push操作会失败。

可正常运行的代码（针对已有自定义字段的联系人） #

let query = "Joe Smith"; 
var found = People.People.searchContacts(
  { 
    "query": query,   
    "readMask": "names,userDefined"
  }); 
thisResult = found.results[0];     
thisResult.person.userDefined[1].key = "HandymanCustID"; 
thisResult.person.userDefined[1].value = "0066"; 
People.People.updateContact(thisResult.person, thisResult.person.resourceName, 
                            {updatePersonFields: "userDefined"});

执行失败的代码（针对无自定义字段的联系人） #

var uDef = new People.newUserDefined();
thisResult.person.userDefined.push(uDef);
thisResult.person.clientData[0].key ="HandymanCustID";
thisResult.person.clientData[0].value = "0066";

解决方案 #

在Tanaike的帮助与多次调试后，编写了以下通用函数，可适配所有场景（无自定义字段、已有字段但无目标key、已有目标key、存在多个重复key）的userDefined字段写入需求：

核心函数代码 #

/**
 * Writes a userDefined field to a Person based on the key:
 *  If the Person has no userDefined fields, add a field.
 *  If they have some, search for the key and overwrite the value.
 *  If they have some and the key doesn't exist, add a field.
 *  If multiple fields with the key exist, display a warning dialog and exit.
 * @param {People.Person} person
 * @param {userDefined} People.person.userDefined
 */
function writeUserDefined(person, newUserDefinedValue){
  let resource;
  if (!person.userDefined)
  {
    Logger.log("   no keys exists");
    Logger.log("   adding new userDefined resource");  
    resource = {
      userDefined: [newUserDefinedValue],
      etag: person.etag
    };
  }
  else if(person.userDefined)
  {
    //if key exists
    index = getIndexUserDefined(person, newUserDefinedValue.key);
    if(index >= 0){
      Logger.log("   key exists");
      Logger.log("   modifying existing field at " + index);
      person.userDefined[index] = newUserDefinedValue;
      resource = person;
    }

    //if key doesn't exist
    else if (index === -1) {
      Logger.log("   key doesn't exist");
      Logger.log("   adding key to end" + index);
      resource = {
        userDefined: [...person.userDefined, newUserDefinedValue],
        etag: person.etag
      };
    }

    //multiple matching keys exist
    else if (index === -2) {
      Logger.log("   multiple keys exist");
      Logger.log("   displaying warning dialog" + index);
      resource = person;
      showMultipleCustomerIDsAlert(person.names[0].displayName);

    }
  }
  else { Logger.log("nothingburger"); return; }
  People.People.updateContact(resource, person.resourceName, 
                            { updatePersonFields: "userDefined" });
}

/**
 * Finds the index in person.userDefined[] of a field containing a specified key
 *  If no userDefined field with the key exists, returns -1
 *  If multiple fields with the key exists, returns -2
 *  Otherwise returns the index of the field with the key.
 * @param {People.person} person
 * @param {String} key
 * @return {Number} getIndexUserDefined
 */
function getIndexUserDefined(person,key){
  let index = -1;
  for(i=0; i < person.userDefined.length; i++){
    if( person.userDefined[i].key === key && index > -1 ){ 
      return -2; 
    }
    else if( person.userDefined[i].key === key && index == -1 ){
      index = i;
    }
  }
  return index;
}

函数说明 #

• 当联系人无userDefined字段时，直接创建包含目标字段的数组并更新
• 当联系人已有userDefined字段时：
  • 若存在目标key，覆盖对应字段的值
  • 若不存在目标key，追加新字段到数组末尾
  • 若存在多个重复的目标key，触发警告弹窗并终止操作

后续计划修改代码以适配Person.externalID字段。

内容的提问来源于stack exchange，提问作者Robert M.