테이블 서비스

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

참조

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

문제를 보고하고 다른 지원을 받으려면 테이블 지원 가이드를 참조하세요.

샘플 코드

테이블 목록 가져오기

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

// 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를 찾으려면 테이블 웹 앱에서 테이블을 엽니다. 상단의 URL에서 테이블 ID는 /table/ 바로 뒤에 있습니다.

아래 샘플은 다양한 표 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입니다.

테이블에서 행 1개 가져오기

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

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 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]"
조회 소스 열 유형에 따라 다릅니다. 이 필드는 수정할 수 없으며 연결된 값으로 업데이트됩니다.
요약 소스 열 유형과 요약 함수에 따라 다릅니다.
개수: Number
날짜 유형 열의 최댓값: 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 속성을 사용할 수 있습니다.

테이블 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