이 페이지는 Cloud Translation API를 통해 번역되었습니다.

방해 금지 시간, 부재중, 근무 위치 일정 관리하기

이 페이지에서는 Google Calendar API를 사용하여 Google Calendar 사용자의 상태를 표시하는 이벤트를 만드는 방법을 설명합니다. 상태 이벤트는 사용자가 방해 금지 시간에 있는지, 부재중인지, 특정 위치에서 근무 중인지 등 사용자의 위치 또는 현재 작업을 설명합니다.

Google Calendar에서 사용자는 방해 금지 시간, 부재중, 근무 위치 이벤트를 만들어 맞춤 상태와 위치를 표시할 수 있습니다. 이 기능은 기본 캘린더 및 일부 Google Calendar 사용자에게만 제공됩니다.

자세한 내용은 Google Calendar에서 방해 금지 시간 사용하기 및 사용자의 근무 위치 사용 또는 사용 중지하기를 참고하세요.

캘린더 상태 이벤트 읽기 및 나열

Calendar API의 Events 리소스에서 Calendar 상태 이벤트를 읽고 나열할 수 있습니다.

상태 이벤트를 읽으려면 events.get 메서드를 사용하여 이벤트의 eventId를 지정합니다.

상태 이벤트를 나열하려면 events.list 메서드를 사용하고 eventTypes 필드에 다음 값 중 하나 이상을 지정합니다.

'focusTime'
'outOfOffice'
'workingLocation'

그런 다음 반환된 Event 객체에서 eventType 필드에 요청된 값이 있는지 검사하고 해당 필드를 참고하여 사용자가 Google Calendar에서 생성한 상태에 관한 세부정보를 확인합니다.

Calendar 상태 일정 만들기 및 업데이트하기

상태 이벤트를 만들려면 events.insert 메서드를 사용하여 Events 리소스의 인스턴스를 만들고 이벤트 유형의 필수 필드를 설정합니다.

events.update 메서드를 사용하여 상태 이벤트를 업데이트하는 경우 이벤트는 필수 필드를 유지해야 합니다.

방해 금지 시간 만들기

방해 금지 시간 일정을 만들려면 다음 단계를 따르세요.

eventType를 'focusTime'로 설정합니다.
focusTimeProperties 필드를 포함합니다.
transparency 필드를 'opaque'로 설정합니다.
이벤트의 start 및 end 필드를 시작 및 종료 시간이 지정된 시간이 지정된 이벤트로 설정합니다.
방해 금지 시간은 종일 일정일 수 없습니다.

기능에 관한 자세한 내용은 Google Calendar에서 방해 금지 시간 사용하기를 참고하세요.

부재중 설정

부재중 일정을 만들려면 다음 단계를 따르세요.

eventType를 'outOfOffice'로 설정합니다.
outOfOfficeProperties 필드를 포함합니다.
transparency 필드를 'opaque'로 설정합니다.
이벤트의 start 및 end 필드를 시작 및 종료 시간이 지정된 시간이 지정된 이벤트로 설정합니다.
부재중 일정은 종일 일정일 수 없습니다.

기능에 관한 자세한 내용은 부재중일 때 표시하기를 참고하세요.

근무 위치 만들기

근무 위치 일정을 만들려면 다음 단계를 따르세요.

eventType를 'workingLocation'로 설정합니다.
workingLocationProperties 필드를 포함합니다.
visibility 필드를 'public'로 설정합니다.
transparency 필드를 'transparent'로 설정합니다.
이벤트의 start 및 end 필드를 다음 중 하나로 설정합니다.
- 시간이 지정된 이벤트 (시작 시간과 종료 시간이 지정됨)
- 정확히 하루 동안 진행되는 종일 이벤트 (시작일과 종료일이 지정됨)입니다.
종일 근무 위치 이벤트는 여러 날에 걸쳐 있을 수 없지만 시간이 지정된 이벤트는 가능합니다.

다음 필드는 선택사항이지만 officeLocation 삽입 시 최상의 사용자 환경을 위해 권장됩니다.

workingLocationProperties.officeLocation.buildingId: 조직의 리소스 데이터베이스의 buildingId와 일치해야 합니다. 이렇게 하면 회의실 추천과 같은 Calendar의 모든 기능을 활용할 수 있습니다.
workingLocationProperties.officeLocation.label: 캘린더 웹 및 모바일 클라이언트에 표시되는 라벨입니다. resources.buildings.list 메서드를 사용하여 건물 ID 및 건물 라벨을 가져올 수 있습니다.

배치 엔드포인트를 통해 근무 위치 이벤트를 만들고 업데이트하는 것은 지원되지 않습니다.

기능에 관한 자세한 내용은 근무 시간 및 위치 설정하기 및 사용자의 근무 위치 사용 또는 사용 중지하기를 참고하세요.

근무 위치 일정 중복을 표시하는 방법

사용자의 캘린더에 근무 위치 일정이 동시에 중복될 수 있습니다. 즉, 주어진 시간에 여러 근무 위치가 설정되어 있을 수 있습니다. 사용자에게 하나의 위치만 표시할 수 있는 경우에는 여러 애플리케이션에서 해당 위치를 일관되게 표시해야 합니다. 이렇게 할 때 다음 가이드라인에 따라 표시할 이벤트를 선택하세요.

시간 지정 이벤트는 종일 이벤트보다 우선합니다.
단일 이벤트는 반복 이벤트 및 예외보다 우선합니다.
나중에 시작되는 이벤트가 일찍 시작되는 이벤트보다 우선 적용됩니다.
기간이 짧은 이벤트는 기간이 긴 이벤트보다 우선합니다.
최근에 생성된 이벤트가 이전에 만들어진 이벤트보다 우선합니다.
부분적으로 중복되는 이벤트는 각각 고유한 근무 위치가 있는 2개의 다른 이벤트로 표시되어야 합니다.

Google Apps Script에서 상태 이벤트 만들기

Google Apps Script는 Google Workspace와 통합되는 비즈니스 애플리케이션을 빌드할 수 있는 자바스크립트 기반 클라우드 스크립팅 언어입니다. 스크립트는 브라우저 기반 코드 편집기에서 개발되며 Google 서버에 저장되고 실행됩니다. Apps Script를 사용하여 Google Calendar API에 요청을 보내려면 Google Apps Script 빠른 시작도 참조하세요.

다음 안내에서는 Google Calendar API를 Google Apps Script의 고급 서비스로 사용하여 상태 이벤트를 관리하는 방법을 설명합니다. Google Calendar API 리소스 및 메서드의 전체 목록은 참조 문서를 확인하세요.

스크립트 작성 및 설정

script.google.com/create로 이동하여 스크립트를 만듭니다.
왼쪽 창에서 서비스 옆의 서비스 추가 를 클릭합니다 .
Google Calendar API를 선택하고 추가를 클릭합니다.
사용 설정되면 API가 왼쪽 창에 표시됩니다. API에서 사용 가능한 메서드와 클래스는 편집기에서 Calendar 키워드를 사용하여 나열할 수 있습니다.

(선택사항) Google Cloud 프로젝트 업데이트

각 Google Apps Script 프로젝트에는 연결된 Google Cloud 프로젝트가 있습니다. 스크립트는 Google Apps Script에서 자동으로 생성되는 기본 프로젝트를 사용할 수 있습니다. 커스텀 Google Cloud 프로젝트를 사용하려면 다음 단계에 따라 스크립트와 연결된 프로젝트를 업데이트합니다.

편집기의 왼쪽에서 프로젝트 설정 을 클릭합니다.
Google Cloud Platform(GCP) 프로젝트에서 프로젝트 변경을 클릭합니다.
개발자 프리뷰 프로그램에 있는 Google Cloud 프로젝트의 프로젝트 번호를 입력하고 프로젝트 설정을 클릭합니다.
왼쪽에서 편집기 를 선택하여 코드 편집기로 다시 이동합니다.

스크립트에 코드 추가

다음 코드 샘플은 기본 캘린더에서 상태 이벤트를 만들고 읽고 나열하는 방법을 보여줍니다.

코드 편집기에 다음을 붙여넣습니다.

primary는 로그인한 사용자의 기본 캘린더에 액세스하는 키워드입니다. 다른 캘린더의 이벤트를 가져오려면 calendarId 매개변수를 이메일 주소로 설정합니다. 이렇게 하면 최소한 한가함/바쁨 액세스 권한이 있는 다른 사용자의 캘린더에서 상태 이벤트를 읽을 수 있습니다. 보조 캘린더에는 상태 일정을 포함할 수 없습니다.

/** Creates a focus time event. */
function createFocusTime() {
  const event = {
    start: { dateTime: '2023-11-14T10:00:00+01:00' },
    end: { dateTime: '2023-11-14T12:00:00+01:00' },
    eventType: 'focusTime',
    focusTimeProperties: {
      chatStatus: 'doNotDisturb',
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am in focus time.',
    }
  }
  createEvent(event);
}

/** Creates an out of office event. */
function createOutOfOffice() {
  const event = {
    start: { dateTime: '2023-11-15T10:00:00+01:00' },
    end: { dateTime: '2023-11-15T18:00:00+01:00' },
    eventType: 'outOfOffice',
    outOfOfficeProperties: {
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am on vacation.',
    }
  }
  createEvent(event);
}

/** Creates a working location event. */
function createWorkingLocation() {
  const event = {
    start: { date: "2023-06-01" },
    end: { date: "2023-06-02" },
    eventType: "workingLocation",
    visibility: "public",
    transparency: "transparent",
    workingLocationProperties: {
      type: 'customLocation',
      customLocation: { label: "a custom location" },
    }
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {
  const calendarId = 'primary';

  try {
    var response = Calendar.Events.insert(event, calendarId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/calendar/api/v3/reference/events/get
  */
function readEvent() {
  const calendarId = 'primary';

  // Replace with a valid eventId.
  const eventId = "sample-event-id";

  try {
    var response = Calendar.Events.get(calendarId, eventId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Lists focus time events. */
function listFocusTimes() {
  listEvents('focusTime');
}

/** Lists out of office events. */
function listOutOfOffices() {
  listEvents('outOfOffice');
}

/** Lists working location events. */
function listWorkingLocations() {
  listEvents('workingLocation');
}

/**
  * Lists events with the given event type.
  * See https://developers.google.com/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = 'default') {
  const calendarId = 'primary'

  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: [eventType],
    showDeleted: false,
    singleEvents: true,
    timeMax: '2023-04-01T00:00:00+01:00',
    timeMin: '2023-03-27T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(calendarId, optionalArgs);
    response.items.forEach(event =>
      console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Parses working location properties of an event into a string.
  * See https://developers.google.com/calendar/api/v3/reference/events#resource
  */
function parseWorkingLocation(event) {
  if (event.eventType != "workingLocation") {
    throw new Error("'" + event.summary + "' is not a working location event.");
  }

  var location = 'No Location';
  const workingLocation = event.workingLocationProperties;
  if (workingLocation) {
    if (workingLocation.type === 'homeOffice') {
      location = 'Home';
    }
    if (workingLocation.type === 'officeLocation') {
      location = workingLocation.officeLocation.label;
    }
    if (workingLocation.type === 'customLocation') {
      location = workingLocation.customLocation.label;
    }
  }
  return `${event.start.date}: ${location}`;
}

코드 샘플 실행

코드 편집기 위의 드롭다운 메뉴에서 실행할 함수를 선택하고 실행을 클릭합니다.
처음 실행하면 액세스를 승인하라는 메시지가 표시됩니다. 검토하고 Apps Script에서 캘린더에 액세스할 수 있도록 허용합니다.
창 하단에 표시되는 실행 로그에서 스크립트 실행 결과를 검사할 수 있습니다.