속성 서비스

Properties 서비스를 사용하면 부가기능이 사용되는 하나의 스크립트, 스크립트의 한 사용자 또는 하나의 문서에 범위가 지정된 키-값 쌍에 간단한 데이터를 저장할 수 있습니다. 일반적으로 개발자 구성이나 사용자 환경설정을 저장하는 데 사용됩니다. 속성은 스크립트 간에 공유되지 않습니다.

속성 서비스의 일일 할당량 및 스토리지 한도를 보려면 Google 서비스 할당량을 참고하세요.

속성 스토어 비교

PropertiesService 전역 객체는 세 가지 메서드를 제공하며, 각 메서드는 다음 표와 같이 유사한 Properties 객체를 반환하지만 액세스 권한이 다릅니다.

스크립트 속성 사용자 속성 문서 속성
액세스 방법 getScriptProperties() getUserProperties() getDocumentProperties()
다음 간에 공유되는 데이터 스크립트, 부가기능 또는 웹 앱의 모든 사용자 스크립트, 부가기능 또는 웹 앱의 현재 사용자 열린 문서의 모든 부가기능 사용자
일반적으로 사용되는 용도 개발자의 외부 데이터베이스의 사용자 이름 및 비밀번호와 같은 앱 전체 구성 데이터 미터법 또는 야드파운드법과 같은 사용자별 설정 삽입된 차트의 소스 URL과 같은 문서별 데이터

데이터 형식

Properties 서비스는 모든 데이터를 키-값 쌍으로 문자열로 저장합니다. 이미 문자열이 아닌 데이터 유형은 저장된 객체 내에 포함된 메서드를 비롯하여 자동으로 문자열로 변환됩니다.

데이터 저장

단일 값을 저장하려면 다음 예와 같이 적절한 저장소의 Properties.setProperty(key, value) 메서드를 호출합니다.

service/propertyService.gs
try {
  // Set a property in each of the three property stores.
  const scriptProperties = PropertiesService.getScriptProperties();
  const userProperties = PropertiesService.getUserProperties();
  const documentProperties = PropertiesService.getDocumentProperties();

  scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
  userProperties.setProperty('DISPLAY_UNITS', 'metric');
  documentProperties.setProperty('SOURCE_DATA_ID',
      '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

데이터를 일괄적으로 저장하려면 키-값 쌍의 맵을 Properties.setProperties(properties)에 전달하세요. 파라미터에 있는 객체의 각 키-값 쌍은 별도의 속성으로 저장됩니다.

service/propertyService.gs
try {
  // Set multiple script properties in one call.
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'cow': 'moo',
    'sheep': 'baa',
    'chicken': 'cluck'
  });
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

데이터 읽기

이전에 저장한 단일 값을 검색하려면 Properties.getProperty(key)를 호출합니다.

service/propertyService.gs
try {
  // Get the value for the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  const units = userProperties.getProperty('DISPLAY_UNITS');
  console.log('values of units %s', units);
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

현재 속성 저장소의 모든 값을 가져오려면 Properties.getProperties()를 호출하세요.

service/propertyService.gs
try {
  // Get multiple script properties in one call, then log them all.
  const scriptProperties = PropertiesService.getScriptProperties();
  const data = scriptProperties.getProperties();
  for (const key in data) {
    console.log('Key: %s, Value: %s', key, data[key]);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

데이터 수정

getProperty() 및 getProperties() 메서드는 저장된 데이터의 사본을 반환하며 라이브 뷰를 반환하지 않으므로 반환된 객체를 변경해도 속성 저장소의 값이 업데이트되지 않습니다. 스토어의 데이터를 업데이트하려면 다시 저장하면 됩니다.

service/propertyService.gs
try {
  // Change the unit type in the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  let units = userProperties.getProperty('DISPLAY_UNITS');
  units = 'imperial'; // Only changes local value, not stored value.
  userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

데이터 삭제

단일 값을 삭제하려면 Properties.deleteProperty(key)를 호출합니다.

service/propertyService.gs
try {
  // Delete the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('DISPLAY_UNITS');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

현재 저장소의 모든 속성을 삭제하려면 Properties.deleteAllProperties()을 호출하세요.

service/propertyService.gs
try {
  // Get user properties in the current script.
  const userProperties = PropertiesService.getUserProperties();
  // Delete all user properties in the current script.
  userProperties.deleteAllProperties();
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

스크립트 속성을 수동으로 관리하기

프로젝트 설정 페이지에서 키-값 쌍의 문자열로 최대 50개의 맞춤 속성을 수동으로 추가할 수 있습니다. 50개가 넘는 속성을 추가하려면 데이터 저장에 설명된 방법을 사용하여 프로그래밍 방식으로 추가해야 합니다. 프로젝트 설정 페이지에서 스크립트 속성을 설정할 때는 스크립트 변수를 참조할 수 없습니다.

스크립트 속성 추가

  1. Apps Script 프로젝트를 엽니다.
  2. 왼쪽에서 프로젝트 설정 프로젝트 설정 아이콘을 클릭합니다.
  3. 첫 번째 속성을 추가하려면 스크립트 속성에서 스크립트 속성 추가를 클릭합니다.
  4. 두 번째 이후 속성을 추가하려면 스크립트 속성에서 스크립트 속성 수정 > 스크립트 속성 추가를 클릭합니다.
  5. 속성에 키 이름을 입력합니다.
  6. 값에 키 값을 입력합니다.
  7. (선택사항) 속성을 더 추가하려면 스크립트 속성 추가를 클릭합니다.
  8. 스크립트 속성 저장을 클릭합니다.

스크립트 속성 수정

  1. Apps Script 프로젝트를 엽니다.
  2. 왼쪽에서 프로젝트 설정 프로젝트 설정 아이콘을 클릭합니다.
  3. 스크립트 속성에서 스크립트 속성 수정을 클릭합니다.
  4. 변경하려는 각 속성의 키 이름과 키 값을 변경합니다.
  5. 스크립트 속성 저장을 클릭합니다.

스크립트 속성 삭제

  1. Apps Script 프로젝트를 엽니다.
  2. 왼쪽에서 프로젝트 설정 프로젝트 설정 아이콘을 클릭합니다.
  3. 스크립트 속성에서 스크립트 속성 수정을 클릭합니다.
  4. 삭제하려는 속성 옆에 있는 삭제 를 클릭합니다.
  5. 스크립트 속성 저장을 클릭합니다.