테이블 서비스

Tables 서비스를 사용하면 스크립트가 프로그래매틱 방식으로 Google Tables 내의 행을 읽고 수정할 수 있습니다.

참조

이 서비스에 관한 자세한 내용은 Tables API 문서를 참고하세요. Apps Script의 모든 고급 서비스와 마찬가지로 Tables 서비스는 공개 API와 동일한 객체, 메서드, 매개변수를 사용합니다. 자세한 내용은 메서드 서명이 결정되는 방식을 참고하세요.

문제를 신고하고 다른 지원을 확인하려면 Tables 지원 가이드를 참고하세요.

샘플 코드

테이블 목록 가져오기

다음 샘플은 사용자가 소유한 모든 테이블의 목록을 가져오는 방법을 보여줍니다.

// Get list of tables the user owns
var response = Area120Tables.Tables.list();
if (response) {
  var tables = response.tables;
  Logger.log(JSON.stringify(tables[0]));
}

다음은 테이블 및 테이블 열 정의에 관한 정보가 포함된 응답의 예입니다.

{
  “tables”: [
    {
      "name": "tables/b6prMlkWyekbsCFeX6IOdu",
      "displayName": "Applicants"
      "columns": [
        {"id": "9qVCMvgh", "name": "Name", "dataType": "text"},
        {"id": "aD8dDXAS", "name": "Email", "dataType": "text"},
        {"id": "9pc0kdNX", "name": "Experience", "dataType": "tags_list",
          "labels": [
            {"id": "aAqi235Q", "name": "Android"},
            {"id": "bULZ4OK3", "name": "iOS"},
          ],
        },
        {"id": "8abYfCyo", "name": "Home Address", "dataType": "location"},
        {"id": "8ccERJ2v", "name": "Doc", "dataType": "file_attachment_list"},
        {"id": "aFb-tXf1", "name": "Stage", "dataType": "dropdown",
          "labels": [
            {"id": "8Hcb-Pxe", "name": "Applied"},
            {"id": "aM3EDGFf", "name": "Phone Screen"},
            {"id": "abyFLVKU", "name": "Onsite Interview"},
          ],
        },
        {"id": "9yKUThTi", "name": "Recruiter", "dataType": "person_list"},
        {"id": "a5c9WPVA", "name": "Interview Date", "dataType": "date"},
        {"id": "bqtbYPtH", "name": "Created", "dataType": "create_timestamp"},
        {"id": "bWR08pBv", "name": "Updated", "dataType": "update_timestamp"}
      ]
    },
    ... // more tables
  ]
}

응답에는 기본적으로 최대 20개의 테이블이 포함됩니다. 더 많은 테이블을 검색하려면 아래에 표시된 page_token 및 page_size 매개변수를 사용하여 응답의 페이지를 만듭니다.

// Paginate through a list of tables
var pageSize = 1000;
var pageToken;
var response = Area120Tables.Tables.list({page_size: pageSize});
while (response) {
  var tables = response.tables;

  // get next page of tables
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.list(tableRequest, {page_size: pageSize, page_token: pageToken});
  }
}

표 목록의 page_size 매개변수의 최대값은 100입니다.

테이블 정보 및 열 정의 가져오기

다음 샘플은 특정 테이블의 정보와 열 정의를 가져오는 방법을 보여줍니다.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.get(tableName);
Logger.log(JSON.stringify(response));

테이블 ID 찾기

표의 ID를 찾으려면 Tables 웹 앱에서 표를 엽니다. 상단의 URL에서 표 ID는 /table/ 바로 뒤에 있습니다.

아래 샘플은 다양한 Tables URL에서 테이블 ID를 찾을 수 있는 위치를 보여줍니다.

https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID/view/abcedfghijk

테이블의 행 읽기

다음 샘플은 테이블 행 목록을 가져오고 필드 값을 읽는 방법을 보여줍니다.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName)
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

샘플 응답은 아래와 같습니다. 응답에는 테이블의 행 목록과 각 필드의 값이 포함됩니다.

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "First item",  // Text
        "Size": 100,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date
        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Purple"
        ],
        "Address": {                  // Location
          "latitude": 40.740726470947266,
          "longitude": -74.00206756591797,
          "address": "3014 Watson Lane, Sattler, TX 78130, USA"
        },
        "Archive?": true,             // Checkbox
        "ID#": 1,                     // Auto ID
        "Row creator": "liz@gmail.com",  // Creator / Updater / Person
        "Last updated": "October 7, 2020 6:30:38 PM EDT",
        "Created on": "March 2, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

응답에는 기본적으로 최대 50개의 행이 포함됩니다. 더 많은 행을 검색하려면 아래와 같이 page_token 및 page_size 매개변수를 사용하여 응답을 페이지로 나눕니다.

var pageToken;
var pageSize = 1000;
var response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize});
while (response) {
  var rows = response.rows;

  // read next page of rows
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize, page_token: pageToken});
  }
}

사용할 수 있는 페이지가 더 있는 경우 응답에 nextPageToken이 제공됩니다. 그렇지 않으면 응답이 정의되지 않습니다. 결과의 다음 페이지를 검색하려면 nextPageToken를 다음 목록 호출에 전달합니다.

page_size 매개변수의 최대값은 1,000입니다.

테이블에서 행 하나 가져오기

다음 샘플은 테이블에서 한 행의 필드 값을 읽는 방법을 보여줍니다.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var rowID = "ROW_ID";  // ID for the row to fetch
var rowName = tableName + "/rows/" + rowID;    // Construct row name
var response = Area120Tables.Tables.Rows.get(rowName)
if (response) {
  Logger.log(response.values);
}

행 목록 필터링

관심 있는 결과만 가져오기 위해 행 목록을 필터링하려면 filter 매개변수를 사용하세요. 필터에서 지원하는 구문 및 열 유형에 관한 자세한 내용은 필터링 API 문서를 참고하세요.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName, {filter:"values.\"Point of Contact\"=\"john.doe@gmail.com\""})
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

응답에 '담당자' 열이 'john.doe@gmail.com'으로 설정된 행이 포함됩니다.

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "Second item",  // Text
        "Size": 110,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date

        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this",
          "finally this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Orange"
        ],
        "Address": {                  // Location
          "latitude": 45.740726470947266,
          "longitude": -88.00206756591797,
          "address": "6027 Holmes Lane, Sattler, TX 78130, USA"
        },
        "Archive?": false,             // Checkbox
        "ID#": 2,                     // Auto ID
        "Point of Contact": "john.doe@gmail.com",  // Person
        "Last updated": "October 9, 2020 6:35:38 PM EDT",
        "Created on": "March 10, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

테이블에 행 만들기

다음 샘플은 테이블에 행을 추가하는 방법을 보여줍니다.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var values = {
    "Number Column": 100,
    "Text Column 2": "hello world",
    "Date Column 3": new Date(),
    "Dropdown Col.": "Dropdown value",
};
Area120Tables.Tables.Rows.create({values: values}, tableName);

새 행에 설정할 값을 지정할 때 객체 키-값 쌍의 키는 쓰기 가능한 열의 유형이 조회 또는 요약 열이 아닌 한 테이블 열의 대소문자를 구분하는 제목과 정확히 일치해야 합니다. 관계의 값을 사용하여 lookup 및 summary 열의 값을 설정합니다. 관계 대화상자에 있는 관계 이름을 사용하여 관계 값을 업데이트해야 합니다.

열에 허용되는 값은 열의 데이터 유형에 따라 다릅니다.

열 유형 데이터 유형 (읽기) 허용되는 입력 유형 (쓰기)
표준 데이터
텍스트 String String
숫자 Number Number
날짜 Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date, String (대부분의 날짜 형식)
리치 데이터
사람 String (이메일 주소) String (Google 사용자와 일치해야 함)
파일 첨부 Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		이 필드는 API로 수정할 수 없습니다.
위치 Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
리치 항목
드롭다운 String String (드롭다운 옵션과 일치해야 함)
태그 String[] (태그 옵션 배열) String[] (태그 옵션과 일치해야 함)
체크박스 Boolean Boolean
체크리스트 String[] (목록 항목 배열) String[] (목록 항목과 일치해야 함)
연결된 데이터
관계 String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
조회 소스 열 유형에 따라 다릅니다. 이 필드는 수정할 수 없으며 연결된 값으로 업데이트됩니다.
요약 소스 열 유형 및 요약 함수에 따라 다릅니다.
Count: Number
Date 유형 열의 최대값: String
값 목록: Array		 이 필드는 수정할 수 없습니다.
계산된 필드
자동 ID Number 이 필드는 수정할 수 없습니다.
메타데이터
만든 사람 String 이 필드는 수정할 수 없습니다.
만들기 시간 Object {
“seconds”: Number,
“nanos”: Number
} 		이 필드는 수정할 수 없습니다.
업데이터 String 이 필드는 수정할 수 없습니다.
업데이트 시간 Object {
“seconds”: Number,
“nanos”: Number
}		 이 필드는 수정할 수 없습니다.

Tables 서비스는 열 유형과 일치하도록 주어진 값을 변환하기 위해 최선을 다합니다. 데이터가 일치하지 않으면 값이 설정되지 않고 새 행의 경우 값이 비워집니다.

테이블에 여러 행 추가

다음 샘플은 테이블에 여러 행을 동시에 추가하는 방법을 보여줍니다. 

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
Area120Tables.Tables.Rows.batchCreate({requests: [
  {row:{values:{"Col 1":"Sample",  "Col 2":"One",   "Col 3":"A"}}},
  {row:{values:{"Col 1":"Example", "Col 2":"Two",   "Col 3":"B"}}},
  {row:{values:{"Col 1":"Test",    "Col 2":"Three", "Col 3":"C"}}},
]}, tableName)

테이블의 행 업데이트

다음 샘플은 테이블에서 기존 행의 값을 업데이트하는 방법을 보여줍니다. 

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var values = {"Column": "HELLO"};
var response = Area120Tables.Tables.Rows.patch({values: values}, rowName);
Logger.log("Update row:" + JSON.stringify(response));
 응답은 업데이트된 행을 반환합니다.

행 ID 찾기

행의 ID는 다음 두 가지 방법으로 찾을 수 있습니다.

API로 행 ID 가져오기

테이블에서 행을 읽을 때는 각 행에 테이블 및 행 ID가 포함된 name 속성을 사용할 수 있습니다.

Tables UI에서 행 ID 가져오기
  1. Tables 웹 앱에서 테이블을 엽니다.
  2. 행을 마우스 오른쪽 버튼으로 클릭합니다.
  3. 이 행의 링크 받기를 클릭합니다.
  4. ID를 복사할 수 있도록 URL을 어딘가에 붙여넣습니다.
  5. URL 내에서 ID는 /row/ 뒤에 있습니다.

아래 샘플은 URL에서 행 ID를 찾을 수 있는 위치를 보여줍니다.

https://tables.area120.google.com/table/TABLE_ID/row/ROW_ID

테이블의 여러 행 업데이트

다음 샘플은 테이블에서 여러 행의 값을 업데이트하는 방법을 보여줍니다. 

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var requests = [
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_1", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_2", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_3", values: {"Column": "WORLD"}}},
];
var response = Area120Tables.Tables.Rows.batchUpdate({requests: requests}, tableName);
Logger.log("Batch update rows:" + JSON.stringify(response));

테이블의 행 삭제

다음 샘플은 테이블에서 단일 행을 삭제하는 방법을 보여줍니다. 

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var response = Area120Tables.Tables.Rows.remove(rowName);
Logger.log("Delete row:" + JSON.stringify(response));

테이블에서 여러 행 삭제

다음 샘플은 테이블에서 여러 행을 삭제하는 방법을 보여줍니다. 

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var rowNames = [
  "tables/TABLE_ID/rows/ROW_ID_1",
  "tables/TABLE_ID/rows/ROW_ID_2",
  "tables/TABLE_ID/rows/ROW_ID_3",
];
Area120Tables.Tables.Rows.batchDelete({names: rowNames}, tableName);

삭제된 행 복원

테이블 UI에서 삭제된 행을 복원할 수 있습니다. 삭제된 행을 복원하려면 다음 단계를 따르세요.

  1. 컴퓨터에서 Tables 웹 앱을 엽니다.
  2. 행을 복원하려는 테이블을 엽니다.
  3. 상단에서 삭제된 행 및 열 표시 를 클릭합니다.
  4. 삭제된 행을 클릭합니다.
  5. 복원하려는 행의 오른쪽에서 휴지통에서 복원 을 클릭합니다.

작업공간 목록 가져오기

다음 샘플은 사용자가 소유한 모든 워크스페이스의 목록을 가져오는 방법을 보여줍니다.

// Get list of workspaces the user owns and lists the tables in each one:
var response = Area120Tables.Workspaces.list();
if (response) {
  var workspaces = response.workspaces;
  for (var workspace of workspaces){
    Logger.log(workspace.displayName);
    for (var table of workspace.tables) {
      Logger.log('Table: ' + table);
    }
  }
}

다음은 출력 로그의 예입니다. 

My Workspace
Table: Table 1
Table: Table 2
My TODOs
Table: Tasks