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

이 페이지에서는 Google Calendar API를 사용하여 Google Calendar 사용자의 상태를 보여주는 일정을 만드는 방법을 설명합니다. 상태 이벤트는 사용자가 어디에 있거나 무엇을 하고 있는지(예: 집중 시간인지, 부재중인지, 특정 위치에서 근무 중인지)를 설명합니다.

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

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

Calendar 상태 이벤트 읽기 및 나열

Calendar API의 Events 리소스에서 Calendar 상태 일정을 읽고 나열할 수 있습니다.

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

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

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

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

상태 이벤트 변경사항 구독

Calendar API의 Events 리소스에서 상태 이벤트의 변경사항을 구독할 수 있습니다.

events.watch 메서드를 사용하여 구독할 캘린더의 calendarId를 지정하고 eventTypes 필드에 다음 값 중 하나 이상을 지정합니다.

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

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를 삽입할 때 최적의 사용자 환경을 위해 권장됩니다.

일괄 처리 엔드포인트를 통해 작업 위치 이벤트를 만들고 업데이트하는 기능은 지원되지 않습니다.

기능 세부정보는 근무 시간 및 위치 설정하기 및 사용자의 근무 위치 사용 또는 사용 중지하기를 참고하세요.

겹치는 근무 위치 활동을 표시하는 방법

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

  • 시간 설정된 일정이 종일 일정보다 우선합니다.
  • 단일 이벤트는 반복 이벤트 및 예외보다 우선합니다.
  • 나중에 시작되는 이벤트가 먼저 시작되는 이벤트보다 우선 적용됩니다.
  • 길이가 짧은 이벤트가 길이가 긴 이벤트보다 우선 적용됩니다.
  • 최근에 생성된 이벤트가 이전에 생성된 이벤트보다 우선 적용됩니다.
  • 부분적으로 겹치는 이벤트는 각각 자체 작업 위치가 있는 두 개의 서로 다른 이벤트로 표시되어야 합니다.

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

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

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

스크립트 만들기 및 설정

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

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

각 Google Apps Script 프로젝트에는 연결된 Google Cloud 프로젝트가 있습니다. 스크립트는 Google Apps Script가 자동으로 만드는 기본 프로젝트를 사용할 수 있습니다. 맞춤 Google Cloud 프로젝트를 사용하려면 다음 단계에 따라 스크립트와 연결된 프로젝트를 업데이트하세요.

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

스크립트에 코드 추가

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

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

    /** 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}`;
}

코드 샘플 실행

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