Google Cloud Search 색인 생성 큐

Connector SDK 및 Google Cloud Search API를 사용하면 다음 태스크를 수행하는 데 사용되는 Cloud Search 색인 생성 큐를 만들 수 있습니다.

  • 색인을 저장소와 동기화 상태로 유지하는 데 사용할 수 있는 문서별 상태(상태, 해시 값 등) 유지관리

  • 순회 프로세스 중에 검색된 대로 색인을 생성할 항목의 목록 유지관리

  • 항목 상태에 따라 큐 항목의 우선순위 지정

  • 체크포인트, 변경 토큰 등 효율적인 통합을 위한 추가 상태 정보 유지관리

큐는 기본 큐의 경우 'default', 큐 B의 경우 'B'와 같이 색인이 생성된 항목에 할당된 라벨입니다.

상태 및 우선순위

큐에서 문서의 우선순위는 ItemStatus 코드에 기반합니다. 다음은 가능한 ItemStatus 코드를 우선순위 (처리되는 순서)대로 나열한 것입니다.

  • ERROR - 색인 생성 프로세스 중에 비동기 오류가 발생하여 다시 색인을 생성해야 하는 항목

  • MODIFIED - 이전에 색인이 생성되었고 마지막 색인이 생성된 후로 저장소에서 수정된 적이 있는 항목

  • NEW_ITEM - 색인이 생성되지 않은 항목

  • ACCEPTED - 이전에 색인이 생성되었고 마지막 색인이 생성된 후로 저장소에서 변경된 적이 없는 문서

큐에 있는 두 항목의 상태가 같을 때 가장 긴 시간 동안 큐에 있었던 항목에 더 높은 우선순위가 부여됩니다.

색인 생성 큐를 사용하여 새 항목 또는 변경된 항목의 색인 생성에 관한 개요

그림 1에서는 색인 생성 큐를 사용하여 새 항목 또는 변경된 항목의 색인을 생성하는 단계를 보여줍니다. 이 단계에서는 REST API 호출을 보여줍니다. 동등한 SDK 호출은 큐 작업 (커넥터 SDK)을 참조하세요.

Google Cloud Search 색인 생성 개요
그림 1. 항목 추가 또는 업데이트를 위한 색인 생성 단계
  1. 콘텐츠 커넥터는 items.push를 사용하여 항목 (메타데이터 및 해시)을 색인 생성 큐에 푸시하여 항목의 상태 (MODIFIED, NEW_ITEM, DELETED)를 설정합니다. 구체적으로는 다음과 같습니다.

    • 푸시하면 커넥터에 푸시 type 또는 contentHash가 명시적으로 포함됩니다.
    • 커넥터에 type가 포함되어 있지 않으면 Cloud Search는 자동으로 contentHash을 사용하여 항목의 상태를 확인합니다.
    • 알 수 없는 항목인 경우 항목 상태는 NEW_ITEM로 설정됩니다.
    • 항목이 있고 해시 값이 일치하면 상태는 ACCEPTED로 유지됩니다.
    • 항목이 있고 해시가 다르면 상태는 MODIFIED가 됩니다.

    항목 상태가 설정되는 방법에 대한 자세한 내용은 Cloud Search 시작하기 가이드에서 GitHub 저장소 탐색 샘플 코드를 참조하세요.

    일반적으로 푸시는 커넥터의 콘텐츠 순회 또는 변경 감지 프로세스와 관련이 있습니다.

  2. 콘텐츠 커넥터는 items.poll로 큐를 폴링하여 색인을 생성할 항목을 결정합니다. Cloud Search는 색인 생성이 가장 필요한 항목을 커넥터에 알려주며, 먼저 상태 코드를 기준으로 정렬한 후 대기 시간순으로 정렬됩니다.

  3. 커넥터는 저장소에서 이러한 항목을 검색하고 색인 API 요청을 빌드합니다.

  4. 커넥터는 items.index를 사용하여 항목의 색인을 생성합니다. Cloud Search에서 항목 처리를 성공적으로 완료한 후에만 항목이 ACCEPTED 상태가 됩니다.

또한 커넥터는 항목이 저장소에 더 이상 존재하지 않는 경우 항목을 삭제하거나, 항목이 수정되지 않았거나 소스 저장소 오류가 있는 경우 항목을 다시 푸시할 수도 있습니다. 항목 삭제에 대한 자세한 내용은 다음 섹션을 참조하세요.

색인 생성 큐를 사용하여 항목 삭제에 관한 개요

전체 순회 전략은 두 큐 프로세스를 사용하여 항목의 색인을 생성하고 삭제를 감지합니다. 그림 2에서는 두 개의 색인 생성 큐를 사용하여 항목을 삭제하는 단계를 보여줍니다. 특히 그림 2에서는 전체 순회 전략을 사용하여 실행되는 두 번째 순회를 보여줍니다. 이 단계에서는 REST API 호출을 사용합니다. 동일한 SDK 호출은 큐 작업 (커넥터 SDK)을 참조하세요.

Google Cloud Search 색인 생성 개요
그림 2. 항목 삭제
  1. 초기 순회 시 콘텐츠 커넥터는 items.push를 사용하여 항목 (메타데이터 및 해시)을 색인 생성 큐 '큐 A'에 NEW_ITEM으로 푸시합니다. 이는 큐에 존재하지 않기 때문입니다. 각 항목에는 '큐 A'에 대해 'A' 라벨이 할당됩니다. 콘텐츠의 색인이 Cloud Search에 생성됩니다.

  2. 콘텐츠 커넥터는 items.poll로 큐 A를 폴링하여 색인을 생성할 항목을 결정합니다. Cloud Search는 색인 생성이 가장 필요한 항목을 커넥터에 알려주며, 먼저 상태 코드를 기준으로 정렬한 후 대기 시간순으로 정렬됩니다.

  3. 커넥터는 저장소에서 이러한 항목을 검색하고 색인 API 요청을 빌드합니다.

  4. 커넥터는 items.index를 사용하여 항목의 색인을 생성합니다. Cloud Search에서 항목 처리를 성공적으로 완료한 후에만 항목이 ACCEPTED 상태가 됩니다.

  5. deleteQueueItems 메서드는 '큐 B'에서 호출됩니다. 하지만 큐 B로 푸시된 항목이 없으므로 어떠한 항목도 삭제할 수 없습니다.

  6. 두 번째 전체 순회 시 콘텐츠 커넥터는 items.push를 사용하여 항목 (메타데이터 및 해시)을 큐 B로 푸시합니다.

    • 푸시하면 커넥터에 푸시 type 또는 contentHash가 명시적으로 포함됩니다.
    • 커넥터에 type가 포함되어 있지 않으면 Cloud Search는 자동으로 contentHash을 사용하여 항목의 상태를 확인합니다.
    • 알 수 없는 항목인 경우 항목 상태가 NEW_ITEM로 설정되고 큐 라벨이 'B'로 변경됩니다.
    • 항목이 있고 해시 값이 일치하면 상태는 ACCEPTED으로 유지되고 큐 라벨이 'B'로 변경됩니다.
    • 항목이 있고 해시가 다르면 상태는 MODIFIED가 되고 큐 라벨이 'B'로 변경됩니다.
  7. 콘텐츠 커넥터는 items.poll로 큐를 폴링하여 색인을 생성할 항목을 결정합니다. Cloud Search는 색인 생성이 가장 필요한 항목을 커넥터에 알려주며, 먼저 상태 코드를 기준으로 정렬한 후 대기 시간순으로 정렬됩니다.

  8. 커넥터는 저장소에서 이러한 항목을 검색하고 색인 API 요청을 빌드합니다.

  9. 커넥터는 items.index를 사용하여 항목의 색인을 생성합니다. Cloud Search에서 항목 처리를 성공적으로 완료한 후에만 항목이 ACCEPTED 상태가 됩니다.

  10. 마지막으로 큐 A에서 deleteQueueItems를 호출하여 이전에 색인 생성된 모든 CCloud Search 항목 중 아직 큐 'A' 라벨이 있는 항목을 삭제합니다.

  11. 후속 전체 순회를 수행하면 색인 생성에 사용되는 큐와 삭제에 사용되는 큐가 교체됩니다.

큐 작업(커넥터 SDK)

콘텐츠 커넥터 SDK는 큐에 항목을 내보내고 큐에서 항목을 가져오는 작업을 제공합니다.

항목을 패키징하고 큐에 푸시하려면 pushItems 빌더 클래스를 사용합니다.

개발자는 큐에서 처리할 항목을 가져오기 위해 특별한 작업을 수행할 필요가 없습니다. 대신 SDK가 Repository 클래스의 getDoc 메서드를 사용하여 우선순위에 따라 큐에서 항목을 자동으로 가져옵니다.

큐 작업(REST API)

REST API는 큐로 항목을 내보내고 큐에서 항목을 가져올 때 다음과 같은 2가지 메소드를 제공합니다.

  • 항목을 큐로 푸시하려면 Items.push를 사용합니다.
  • 큐의 항목을 폴링하려면 Items.poll를 사용합니다.

또한 Items.index를 사용하여 색인 생성 중에 큐로 항목을 푸시할 수 있습니다. 색인 생성 중에 큐로 푸시된 항목에는 type가 필요하지 않으며 자동으로 ACCEPTED 상태가 할당됩니다.

Items.push

Items.push 메서드는 큐에 ID를 추가합니다. 이 메서드는 푸시 작업의 결과를 결정하는 특정 type 값을 사용하여 호출할 수 있습니다. type 값 목록은 Items.push 메서드의 item.type 필드를 참조하세요.

새 ID를 푸시하면 NEW_ITEM ItemStatus 코드를 사용하여 새 항목이 추가됩니다.

선택적 페이로드는 항상 저장되고 불투명 값으로 처리되며 Items.poll에서 반환됩니다.

항목이 폴링되면 예약됩니다. 즉, Items.poll를 다시 호출해도 항목이 반환될 수 없습니다. Items.pushtype와 함께 NOT_MODIFIED, REPOSITORY_ERROR 또는 REQUEUE로 사용하면 폴링된 항목이 예약 취소됩니다. 예약된 항목과 예약되지 않은 항목에 대한 자세한 내용은 Items.poll 섹션을 참조하세요.

해시가 있는 Items.push

Google Cloud Search API는 Items.index 요청에 메타데이터 및 콘텐츠 해시 값 지정을 지원합니다. type를 지정하는 대신 메타데이터 또는 콘텐츠 해시 값을 푸시 요청으로 지정할 수 있습니다. Cloud Search 색인 생성 큐는 제공된 해시 값과 데이터 소스의 항목에서 사용 가능한 저장된 값을 비교합니다. 일치하지 않으면 해당 항목이 MODIFIED로 표시됩니다. 해당 항목이 색인에 없으면 상태는 NEW_ITEM입니다.

Items.poll

Items.poll 메소드는 큐에서 가장 우선순위가 높은 항목을 검색합니다. 요청된 상태 값은 요청된 우선순위 큐의 상태 또는 반환된 ID의 상태를 나타냅니다.

기본적으로 큐의 모든 섹션에 있는 항목이 우선순위에 따라 반환될 수 있습니다. 반환된 각 항목은 예약되며 다음 사례 중 하나를 충족할 때까지 다른 Items.poll 호출로 반환되지 않습니다.

  • 예약이 타임아웃된 경우
  • Items.index에 의해 항목이 다시 대기열에 추가됩니다.
  • Items.pushNOT_MODIFIED, REPOSITORY_ERROR 또는 REQUEUEtype 값으로 호출됩니다.