파일 알림 모드에서 자동 로더 스트림 구성

이 페이지에서는 파일 알림 모드를 사용하여 클라우드 데이터를 증분 방식으로 검색하고 수집하도록 자동 로더 스트림을 구성하는 방법을 설명합니다.

파일 알림 모드에서 자동 로더는 입력 디렉터리의 파일 이벤트를 구독하는 알림 서비스 및 큐 서비스를 자동으로 설정합니다. 파일 알림을 사용하여 한 시간에 수백만 개의 파일을 수집하도록 자동 로더를 스케일링할 수 있습니다. 디렉터리 목록 모드와 비교할 때 파일 알림 모드는 성능이 향상되고 확장 가능합니다.

파일 알림과 디렉터리 목록 간에 언제든지 전환할 수 있으며, 정확히 한 번만 데이터를 처리하도록 보장할 수 있습니다.

참고

프리미엄 계정은 큐 스토리지를 지원하지 않으므로 Azure Premium Storage 계정에는 파일 알림 모드가 지원되지 않습니다.

경고

자동 로더 의 원본 경로 변경은 파일 알림 모드에서 지원되지 않습니다. 파일 알림 모드를 사용하고 경로가 변경된 경우 디렉터리 업데이트 시 새 디렉터리에 이미 있는 파일을 수집하지 못할 수 있습니다.

외부 위치에서 파일 이벤트를 사용 또는 사용하지 않는 파일 알림 모드

파일 알림 모드를 사용하도록 자동 로더를 구성하는 방법에는 두 가지가 있습니다.

• 레거시 파일 알림 모드: 각 자동 로더 스트림에 대한 파일 알림 큐를 개별적으로 관리합니다. 자동 로더는 입력 디렉터리에서 파일 이벤트를 구독하는 알림 서비스 및 큐 서비스를 자동으로 설정합니다.

  이것이 레거시 접근 방식입니다.

• (권장) 파일 이벤트 (공개 미리 보기): Unity 카탈로그에 정의된 지정된 외부 위치에서 파일을 처리하는 모든 스트림에 단일 Azure Databricks 관리 파일 알림 큐를 사용합니다.

  이 방법을 사용하려면 외부 위치에 대한 파일 이벤트를 사용하도록 설정해야 합니다. 레거시 접근 방식에 비해 다음과 같은 이점이 있습니다.

  • Azure Databricks는 서비스 자격 증명 또는 기타 클라우드 특정 인증 옵션을 사용하여 자동 로더에 추가 자격 증명을 제공할 필요 없이 클라우드 스토리지 계정에서 구독 및 파일 이벤트를 설정할 수 있습니다. 외부 위치에 대한 파일 이벤트 사용(권장)을 참조하세요.
  • 클라우드 스토리지 계정에서 만들 Azure 관리 ID 정책이 더 적습니다.
  • 각 자동 로더 스트림에 대한 큐를 더 이상 만들 필요가 없으므로 레거시 자동 로더 파일 알림 모드에서 사용되는 클라우드 리소스에 나열된 클라우드 공급자 알림 제한에 도달하는 것을 방지하는 것이 더 쉽습니다.
  • Azure Databricks는 리소스 요구 사항의 튜닝을 자동으로 관리하므로 다음과 같은 cloudFiles.fetchParallelism매개 변수를 조정할 필요가 없습니다.
  • 정리 기능은 스트림이 삭제되거나 완전히 새로 고쳐지는 경우와 같이 클라우드에서 생성되는 알림의 수명 주기에 대해 걱정할 필요가 없다는 것을 의미합니다.

Databricks는 현재 디렉터리 목록 모드에서 자동 로더를 사용하는 경우 파일 이벤트와 함께 파일 알림 모드로 마이그레이션하여 성능이 크게 향상되는 것을 확인하는 것이 좋습니다.

파일 이벤트와 함께 파일 알림 모드 사용

이 섹션에서는 파일 이벤트를 사용하도록 자동 로더 스트림을 만들고 업데이트하는 방법을 설명합니다.

중요한

파일 이벤트에 대한 자동 로더 지원은 공개 미리 보기로 제공됩니다. 미리 보기에 등록하려면 Azure Databricks 계정 팀에 문의하세요.

시작하기 전 주의 사항:

파일 이벤트를 설정하려면 다음이 필요합니다.

• Unity 카탈로그에 사용하도록 설정된 Azure Databricks 작업 영역입니다.
• Unity 카탈로그에서 스토리지 자격 증명 및 외부 위치 개체를 만들 수 있는 권한입니다.

파일 이벤트가 있는 자동 로더 스트림에는 다음이 필요합니다.

• Databricks Runtime 14.3 LTS 이상에서 컴퓨팅합니다.

파일 이벤트를 사용하는 자동 로더 스트림을 만들거나 업데이트하기 전에 다음을 수행합니다.

• 외부 위치에서 데이터를 사용하는 기존 알림 기반 자동 로더 스트림 이 있는지 확인합니다. 이 경우 해당 리소스를 끄고 연결된 알림 리소스를 삭제합니다.

구성 지침

다음 지침은 새 자동 로더 스트림을 만들거나 파일 이벤트와 함께 업그레이드된 파일 알림 모드를 사용하도록 기존 스트림을 마이그레이션하는지에 따라 적용됩니다.

1. 자동 로더 스트림에 대한 클라우드 스토리지의 원본 위치에 대한 액세스 권한을 부여하는 스토리지 자격 증명 및 외부 위치를 Unity 카탈로그에 만듭니다. 클라우드 스토리지를 Azure Databricks에 연결하기 위한 외부 위치 생성 방법을 참조하세요.

2. 외부 위치에 대한 파일 이벤트를 사용하도록 설정합니다. 외부 위치에 대한 파일 이벤트 사용(권장)을 참조하세요.

3. 새 자동 로더 스트림을 만들거나 외부 위치에서 작업하도록 기존 스트림을 편집하는 경우:

   • 외부 위치에서 데이터를 사용하는 기존 알림 기반 자동 로더 스트림 이 있는 경우 해당 스트림을 끄고 연결된 알림 리소스를 삭제합니다.
   • pathRewrites 설정되지 않았는지 확인합니다(일반적인 옵션이 아님).
   • 자동 로더가 파일 이벤트를 사용하여 파일 알림을 관리할 때 무시하는 설정 목록을 검토합니다. 새 자동 로더 스트림에서 해당 스트림을 방지하고 이 모드로 마이그레이션하는 기존 스트림에서 제거합니다.
   • 자동 로더 코드에서 옵션을 cloudFiles.useManagedFileEventstrue 설정합니다.

다음은 그 예입니다.

autoLoaderStream = (spark.readStream
  .format("cloudFiles")
  ...
  .options("cloudFiles.useManagedFileEvents", True)
  ...)

Lakeflow 선언적 파이프라인을 사용하고 있고 스트리밍 테이블을 포함한 파이프라인이 이미 있는 경우, useManagedFileEvents 옵션을 포함하도록 업데이트하십시오.

CREATE OR REFRESH STREAMING LIVE TABLE <table-name>
AS SELECT <select clause expressions>
  FROM STREAM read_files('abfss://path/to/external/location/or/volume',
                   format => '<format>',
                   useManagedFileEvents => 'True'
                   ...
                   );

지원되지 않는 자동 로더 설정

다음 자동 로더 설정은 스트림에서 파일 이벤트를 사용할 때 지원되지 않습니다.

설정	변화
useIncremental	파일 알림의 효율성과 디렉터리 목록의 단순성 중에서 더 이상 결정할 필요가 없습니다. 파일 이벤트가 있는 자동 로더는 한 가지 모드로 제공됩니다.
useNotifications	외부 위치당 하나의 큐 및 스토리지 이벤트 구독만 있습니다.
cloudFiles.fetchParallelism	파일 이벤트가 있는 자동 로더는 수동 병렬 처리 최적화를 제공하지 않습니다.
cloudFiles.backfillInterval	Azure Databricks는 파일 이벤트에 사용하도록 설정된 외부 위치에 대해 자동으로 백필을 처리합니다.
cloudFiles.pathRewrites	이 옵션은 사용 중지된 DBFS에 외부 데이터 위치를 마운트할 때만 적용됩니다.
resourceTags	클라우드 콘솔을 사용하여 리소스 태그를 설정해야 합니다.

파일 이벤트가 있는 자동 로더에 대한 제한 사항

파일 이벤트 서비스는 가장 최근에 만든 파일을 캐싱하여 파일 검색을 최적화합니다. 자동 로더가 자주 실행되지 않는 경우 이 캐시는 만료되고 자동 로더는 디렉터리 목록으로 돌아가 파일을 검색하고 캐시를 업데이트합니다. 이 시나리오를 방지하려면 7일마다 한 번 이상 자동 로더를 호출합니다.

파일 이벤트에 대한 일반적인 제한 목록은 파일 이벤트 제한 사항을 참조하세요.

각 자동 로더 스트림에 대한 파일 알림 큐를 개별적으로 관리(레거시)

중요한

파일 알림 모드에 대한 클라우드 인프라를 자동으로 구성하려면 상승된 권한이 필요합니다. 클라우드 관리자 또는 작업 영역 관리자에게 문의하세요. 참조:

• Azure Data Lake Storage 및 Azure Blob Storage에 대한 파일 알림을 구성하는 데 필요한 권한
• Amazon S3 대한 파일 알림을 구성하는 데 필요한 권한
• GCS에 대한 파일 알림 구성에 필요한 권한

레거시 자동 로더 파일 알림 모드에서 사용되는 클라우드 리소스

자동 로더는 옵션 cloudFiles.useNotificationstrue 설정하고 클라우드 리소스를 만드는 데 필요한 권한을 제공할 때 자동으로 파일 알림을 설정할 수 있습니다. 또한 자동 로더가 이러한 리소스를 생성할 수 있도록 권한을 부여하기 위해 추가 옵션을 제공해야 할 수도 있습니다.

다음 표에서는 각 클라우드 공급자에 대해 자동 로더에서 만든 리소스를 나열합니다.

클라우드 스토리지	구독 서비스	큐 서비스	접두사 *	한계**
Amazon S3	AWS SNS	AWS SQS	databricks-자동-인제스트	S3 버킷당 100
ADLS	Azure Event Grid	Azure Queue Storage (Azure 대기열 저장소)	데이터브릭스	스토리지 계정당 500
GCS	Google Pub/Sub (Google의 메시징 서비스)	Google Pub/Sub (Google의 메시징 서비스)	databricks-자동-인제스트	GCS 버킷당 100
Azure Blob Storage (Azure 블롭 스토리지)	Azure Event Grid	Azure Queue Storage (Azure 대기열 저장소)	데이터브릭스	스토리지 계정당 500

* 자동 로더는 이 접두사를 사용하여 리소스의 이름을 지정합니다.

** 동시에 실행할 수 있는 파일 알림 파이프라인 수

이러한 제한에서 허용하는 것보다 더 많은 파일 알림 기반 자동 로더 스트림을 실행해야 하는 경우 파일 이벤트 또는 AWS 람다, Azure Functions 또는 Google Cloud Functions와 같은 서비스를 사용하여 전체 컨테이너 또는 버킷을 수신 대기하는 단일 큐에서 디렉터리별 큐로 알림을 팬아웃할 수 있습니다.

레거시 파일 알림 이벤트

Amazon S3는 파일이 S3 버킷에 업로드될 때, 그것이 put 업로드든 다중 파트 업로드든 상관없이 ObjectCreated 이벤트를 제공합니다.

Azure Data Lake Storage는 스토리지 컨테이너에 표시되는 파일에 대해 다양한 이벤트 알림을 제공합니다.

• 자동 로더는 파일 처리를 위해 FlushWithClose 이벤트를 수신 대기합니다.
• 자동 로더 스트림은 RenameFile 파일 검색 작업을 지원합니다. RenameFile 작업을 수행하려면 이름이 바뀐 파일의 크기를 가져오기 위해 스토리지 시스템에 대한 API 요청이 필요합니다.
• Databricks Runtime 9.0 이상에서 만든 자동 로더 스트림은 파일 검색을 위한 RenameDirectory 작업을 지원합니다. RenameDirectory 작업을 수행하려면 이름이 바뀐 디렉터리의 내용을 나열하기 위해 스토리지 시스템에 대한 API 요청이 필요합니다.

Google Cloud Storage는 덮어쓰기 및 파일 복사를 포함하여 파일이 업로드될 때 OBJECT_FINALIZE 이벤트를 제공합니다. 실패한 업로드는 이 이벤트를 생성하지 않습니다.

참고

클라우드 공급자는 매우 드문 조건에서 모든 파일 이벤트의 100% 배달을 보장하지 않으며 파일 이벤트의 대기 시간에 엄격한 SLA를 제공하지 않습니다. Databricks는 데이터 완전성이 요구 사항인 경우 지정된 SLA 내에서 모든 파일이 검색되도록 보장하기 위해 cloudFiles.backfillInterval 옵션을 사용하여 자동 로더로 정기적인 백필을 트리거하는 것이 좋습니다. 일반 백필을 트리거해도 중복이 발생하지 않습니다.

Azure Data Lake Storage 및 Azure Blob Storage에 대한 파일 알림을 구성하는 데 필요한 권한

입력 디렉터리에 대한 읽기 권한이 있어야 합니다. Azure Blob Storage를 참조하세요.

파일 알림 모드를 사용하려면 이벤트 알림 서비스를 설정하고 액세스하기 위한 인증 자격 증명을 제공해야 합니다.

다음 방법 중 하나를 사용하여 인증할 수 있습니다.

• Databricks Runtime 16.1 이상: Databricks 서비스 자격 증명(권장): 관리 ID 및 Databricks 액세스 커넥터를 사용하여 서비스 자격 증명 을 만듭니다.
• 서비스 주체: 클라이언트 ID 및 클라이언트 암호 형식으로 Microsoft Entra ID(이전의 Azure Active Directory) 앱 및 서비스 주체 만듭니다.

인증 자격 증명을 얻은 후 Databricks 액세스 커넥터(서비스 자격 증명용) 또는 Microsoft Entra ID 앱(서비스 주체의 경우)에 필요한 권한을 할당합니다.

• Azure 기본 제공 역할 사용

  입력 경로가 있는 스토리지 계정에 다음 역할을 액세스 커넥터에 할당합니다.

  • 기여자: 이 역할은 큐, 이벤트 구독과 같은 스토리지 계정의 리소스를 설정하는 데 사용됩니다.
  • Storage 큐 데이터 기여자: 이 역할은 큐에서 메시지 검색 및 삭제와 같은 큐 작업을 수행하기 위한 것입니다. 이 역할은 연결 문자열 없이 서비스 주체를 제공하는 경우에만 필요합니다.

  이 액세스 커넥터를 관련 리소스 그룹에 다음 역할을 할당합니다.

  • Azure Event Grid EventSubscription 기여자: 이 역할은 Azure Event Grid(이벤트 그리드)에서 이벤트 구독을 만들거나 나열하는 등의 구독 작업을 수행하기 위한 것입니다.

  자세한 내용은 Azure Portal을 사용하여 Azure 역할 할당을 참조하십시오.

• 사용자 지정 역할 사용

  이전 역할에 필요한 과도한 사용 권한과 관련된 경우 Azure 역할 JSON 형식으로 아래에 나열된 다음 권한 이상을 사용하여 사용자 지정 역할을 만들 수 있습니다.

  "permissions": [
    {
      "actions": [
        "Microsoft.EventGrid/eventSubscriptions/write",
        "Microsoft.EventGrid/eventSubscriptions/read",
        "Microsoft.EventGrid/eventSubscriptions/delete",
        "Microsoft.EventGrid/locations/eventSubscriptions/read",
        "Microsoft.Storage/storageAccounts/read",
        "Microsoft.Storage/storageAccounts/write",
        "Microsoft.Storage/storageAccounts/queueServices/read",
        "Microsoft.Storage/storageAccounts/queueServices/write",
        "Microsoft.Storage/storageAccounts/queueServices/queues/write",
        "Microsoft.Storage/storageAccounts/queueServices/queues/read",
        "Microsoft.Storage/storageAccounts/queueServices/queues/delete"
    ],
      "notActions": [],
      "dataActions": [
        "Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete",
        "Microsoft.Storage/storageAccounts/queueServices/queues/messages/read",
        "Microsoft.Storage/storageAccounts/queueServices/queues/messages/write",
        "Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action"
      ],
      "notDataActions": []
    }
  ]
  

  그런 다음, 액세스 커넥터에 이 사용자 지정 역할을 할당할 수 있습니다.

  자세한 내용은 Azure Portal을 사용하여 Azure 역할 할당을 참조하십시오.

자동 로더 권한 설정

Amazon S3에 대한 파일 알림을 구성하는 데 필요한 권한

입력 디렉터리에 대한 읽기 권한이 있어야 합니다. 자세한 내용은 S3 연결 세부 정보를 참조하세요.

파일 알림 모드를 사용하려면 다음 JSON 정책 문서를 IAM 사용자 또는 역할에 연결합니다. 이 IAM 역할은 인증할 자동 로더에 대한 서비스 자격 증명을 만드는 데 필요합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderSetup",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "s3:PutBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:CreateTopic",
        "sns:TagResource",
        "sns:Publish",
        "sns:Subscribe",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    },
    {
      "Sid": "DatabricksAutoLoaderList",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "*"
    },
    {
      "Sid": "DatabricksAutoLoaderTeardown",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    }
  ]
}

어디:

• <bucket-name>: 스트림이 파일을 읽을 S3 버킷 이름(예: auto-logs)입니다. *를 와일드카드로 사용할 수 있습니다(예: databricks-*-logs). DBFS 경로에 대한 기본 S3 버킷을 확인하려면 %fs mounts실행하여 Notebook의 모든 DBFS 탑재 지점을 나열할 수 있습니다.
• <region>: S3 버킷이 있는 AWS 지역(예: us-west-2)입니다. 지역을 지정하지 않으려면 .를 사용합니다 *.
• <account-number>: S3 버킷을 소유하는 AWS 계정 번호입니다(예: 123456789012). 계정 번호를 지정하지 않으려면 .를 사용합니다 *.

SQS 및 SNS ARN 사양의 databricks-auto-ingest-* 문자열은 SQS 및 SNS 서비스를 만들 때 cloudFiles 원본에서 사용하는 이름 접두사입니다. Azure Databricks는 스트림의 초기 실행에서 알림 서비스를 설정하므로 초기 실행 후에는 권한이 축소된 정책을 사용할 수 있습니다. 예를 들어, 스트림을 중지한 후 다시 시작할 수 있습니다.

참고

앞의 정책은 파일 알림 서비스(즉, S3 버킷 알림), SNS 및 SQS 서비스를 설정하는 데 필요한 권한에만 관련되며 사용자에게 이미 S3 버킷에 대한 읽기 권한이 있다고 가정합니다. S3의 읽기 전용 권한을 추가하려면 JSON 문서의 Action 구문의 DatabricksAutoLoaderSetup 목록에 다음을 추가합니다.

• s3:ListBucket
• s3:GetObject

초기 설정 후 권한 감소

위에서 설명한 리소스 설정 권한은 스트림의 초기 실행 중에만 필요합니다. 첫 번째 실행 후 권한이 감소된 다음 IAM 정책으로 전환할 수 있습니다.

중요한

권한이 감소하면 새 스트리밍 쿼리를 시작하거나 오류가 발생할 경우 리소스를 다시 만들 수 없습니다(예: SQS 큐가 실수로 삭제됨). 또한 클라우드 리소스 관리 API를 사용하여 리소스를 나열하거나 해제할 수 없습니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderUse",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:TagResource",
        "sns:Publish",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:<queue-name>",
        "arn:aws:sns:<region>:<account-number>:<topic-name>",
        "arn:aws:s3:::<bucket-name>"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::<bucket-name>"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::<bucket-name>/*"]
    },
    {
      "Sid": "DatabricksAutoLoaderListTopics",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "arn:aws:sns:<region>:<account-number>:*"
    }
  ]
}

GCS에 대한 파일 알림 구성에 필요한 권한

GCS 버킷과 모든 개체에 대한 list 및 get 권한이 있어야 합니다. 자세한 내용은 IAM 권한에 대한 Google 설명서를 참조하세요.

파일 알림 모드를 사용하려면 GCS 서비스 계정 및 Google Cloud Pub/Sub 리소스에 액세스하는 데 사용되는 서비스 계정에 대한 권한을 추가해야 합니다.

GCS 서비스 계정에 Pub/Sub Publisher 역할을 추가합니다. 이렇게 하면 계정에서 GCS 버킷의 이벤트 알림 메시지를 Google Cloud Pub/Sub에 게시할 수 있습니다.

Google Cloud Pub/Sub 리소스에 사용되는 서비스 계정에 대해서는 다음 권한을 추가해야 합니다. 이 서비스 계정은 Databricks 서비스 자격 증명만들 때 자동으로 만들어집니다. 서비스 자격 증명 지원은 Databricks Runtime 16.1 이상에서 사용할 수 있습니다.

pubsub.subscriptions.consume
pubsub.subscriptions.create
pubsub.subscriptions.delete
pubsub.subscriptions.get
pubsub.subscriptions.list
pubsub.subscriptions.update
pubsub.topics.attachSubscription
pubsub.topics.create
pubsub.topics.delete
pubsub.topics.get
pubsub.topics.list
pubsub.topics.update

이렇게 하려면 이러한 권한으로 IAM 사용자 지정 역할을 만들거나기존 GCP 역할을 할당하여 이러한 권한을 처리할 수 있습니다.

GCS 서비스 계정 찾기

해당 프로젝트의 Google Cloud 콘솔에서 Cloud Storage > Settings로 이동합니다. "Cloud Storage 서비스 계정" 섹션에는 GCS 서비스 계정의 이메일이 포함되어 있습니다.

파일 알림 모드에 대한 사용자 지정 Google Cloud IAM 역할 만들기

해당 프로젝트의 Google Cloud 콘솔에서 IAM & Admin > Roles로 이동합니다. 그런 다음 맨 위에 역할을 만들거나 기존 역할을 업데이트합니다. 역할 만들기 또는 편집 화면에서 Add Permissions를 클릭합니다. 역할에 원하는 권한을 추가할 수 있는 메뉴가 나타납니다.

파일 알림 리소스 수동 구성 또는 관리

권한 있는 사용자는 파일 알림 리소스를 수동으로 구성하거나 관리할 수 있습니다.

• 클라우드 공급자를 통해 파일 알림 서비스를 수동으로 설정하고 큐 식별자를 수동으로 지정합니다. 자세한 내용은 파일 알림 옵션을 참조하세요.
• 다음 예제와 같이 Scala API를 사용하여 알림 및 큐 서비스를 만들거나 관리합니다.

참고

클라우드 인프라를 구성하거나 수정하려면 적절한 권한이 있어야 합니다. Azure, S3 또는 GCS에 대한 권한 설명서를 참조하세요.

파이썬

# Databricks notebook source
# MAGIC %md ## Python bindings for CloudFiles Resource Managers for all 3 clouds

# COMMAND ----------

#####################################
## Creating a ResourceManager in AWS
#####################################

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .create()

# Using AWS access key and secret key
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("cloudFiles.awsAccessKey", <aws-access-key>) \
  .option("cloudFiles.awsSecretKey", <aws-secret-key>) \
  .option("cloudFiles.roleArn", <role-arn>) \
  .option("cloudFiles.roleExternalId", <role-external-id>) \
  .option("cloudFiles.roleSessionName", <role-session-name>) \
  .option("cloudFiles.stsEndpoint", <sts-endpoint>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

#######################################
## Creating a ResourceManager in Azure
#######################################

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

# Using an Azure service principal
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.connectionString", <connection-string>) \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("cloudFiles.tenantId", <tenant-id>) \
  .option("cloudFiles.clientId", <service-principal-client-id>) \
  .option("cloudFiles.clientSecret", <service-principal-client-secret>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

#######################################
## Creating a ResourceManager in GCP
#######################################

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

# Using a Google service account
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("cloudFiles.client", <client-id>) \
  .option("cloudFiles.clientEmail", <client-email>) \
  .option("cloudFiles.privateKey", <private-key>) \
  .option("cloudFiles.privateKeyId", <private-key-id>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

# Set up a queue and a topic subscribed to the path provided in the manager.
manager.setUpNotificationServices(<resource-suffix>)

# List notification services created by <AL>
from pyspark.sql import DataFrame
df = DataFrame(manager.listNotificationServices(), spark)

# Tear down the notification services created for a specific stream ID.
# Stream ID is a GUID string that you can find in the list result above.
manager.tearDownNotificationServices(<stream-id>)

스칼라

/////////////////////////////////////
// Creating a ResourceManager in AWS
/////////////////////////////////////

import com.databricks.sql.CloudFilesAWSResourceManager

/**
 * Using a Databricks service credential
 */
val manager = CloudFilesAWSResourceManager
    .newManager
    .option("cloudFiles.region", <region>) // optional, will use the region of the EC2 instances by default
    .option("databricks.serviceCredential", <service-credential-name>)
    .option("path", <path-to-specific-bucket-and-folder>) // required only for setUpNotificationServices
    .create()

/**
 * Using AWS access key and secret key
 */
val manager = CloudFilesAWSResourceManager
    .newManager
    .option("cloudFiles.region", <region>)
    .option("cloudFiles.awsAccessKey", <aws-access-key>)
    .option("cloudFiles.awsSecretKey", <aws-secret-key>)
    .option("cloudFiles.roleArn", <role-arn>)
    .option("cloudFiles.roleExternalId", <role-external-id>)
    .option("cloudFiles.roleSessionName", <role-session-name>)
    .option("cloudFiles.stsEndpoint", <sts-endpoint>)
    .option("path", <path-to-specific-bucket-and-folder>) // required only for setUpNotificationServices
    .create()

///////////////////////////////////////
// Creating a ResourceManager in Azure
///////////////////////////////////////

import com.databricks.sql.CloudFilesAzureResourceManager

/**
 * Using a Databricks service credential
 */
val manager = CloudFilesAzureResourceManager
  .newManager
  .option("cloudFiles.resourceGroup", <resource-group>)
  .option("cloudFiles.subscriptionId", <subscription-id>)
  .option("databricks.serviceCredential", <service-credential-name>)
  .option("path", <path-to-specific-container-and-folder>) // required only for setUpNotificationServices
  .create()

/**
 * Using an Azure service principal
 */
val manager = CloudFilesAzureResourceManager
  .newManager
  .option("cloudFiles.connectionString", <connection-string>)
  .option("cloudFiles.resourceGroup", <resource-group>)
  .option("cloudFiles.subscriptionId", <subscription-id>)
  .option("cloudFiles.tenantId", <tenant-id>)
  .option("cloudFiles.clientId", <service-principal-client-id>)
  .option("cloudFiles.clientSecret", <service-principal-client-secret>)
  .option("path", <path-to-specific-container-and-folder>) // required only for setUpNotificationServices
  .create()

///////////////////////////////////////
// Creating a ResourceManager in GCP
///////////////////////////////////////

import com.databricks.sql.CloudFilesGCPResourceManager

/**
 * Using a Databricks service credential
 */
val manager = CloudFilesGCPResourceManager
    .newManager
    .option("cloudFiles.projectId", <project-id>)
    .option("databricks.serviceCredential", <service-credential-name>)
    .option("path", <path-to-specific-bucket-and-folder>) // Required only for setUpNotificationServices.
    .create()

/**
 * Using a Google service account
 */
val manager = CloudFilesGCPResourceManager
    .newManager
    .option("cloudFiles.projectId", <project-id>)
    .option("cloudFiles.client", <client-id>)
    .option("cloudFiles.clientEmail", <client-email>)
    .option("cloudFiles.privateKey", <private-key>)
    .option("cloudFiles.privateKeyId", <private-key-id>)
    .option("path", <path-to-specific-bucket-and-folder>) // Required only for setUpNotificationServices.
    .create()

// Set up a queue and a topic subscribed to the path provided in the manager.
manager.setUpNotificationServices(<resource-suffix>)

// List notification services created by <AL>
val df = manager.listNotificationServices()

// Tear down the notification services created for a specific stream ID.
// Stream ID is a GUID string that you can find in the list result above.
manager.tearDownNotificationServices(<stream-id>)

이름으로 큐 및 구독을 만드는 데 사용합니다setUpNotificationServices(<resource-suffix>)(접두사는 <prefix>-<resource-suffix> 요약된 스토리지 시스템에 따라 달라집니다. 이름이 같은 기존 리소스가 있는 경우 Azure Databricks는 새 리소스를 만드는 대신 기존 리소스를 재사용합니다. 이 함수는 cloudFiles의 식별자를 사용하여 원본에 전달할 수 있는 큐 식별자를 반환합니다. 이렇게 하면 cloudFiles 원본 사용자가 리소스를 만드는 사용자보다 적은 권한을 가질 수 있습니다.

"path"를 호출하는 경우에만 newManager 옵션을 setUpNotificationServices에 제공합니다. listNotificationServices 또는 tearDownNotificationServices에는 필요하지 않습니다. 이는 스트리밍 쿼리를 실행할 때 사용하는 것과 동일한 path입니다.

다음 매트릭스는 각 스토리지 유형에 대해 Databricks Runtime에서 지원되는 API 메서드를 나타냅니다.

클라우드 스토리지	설치 API입니다	목록 API	API 분해
Amazon S3	모든 버전	모든 버전	모든 버전
ADLS	모든 버전	모든 버전	모든 버전
GCS	Databricks Runtime 9.1 이상	Databricks Runtime 9.1 이상	Databricks Runtime 9.1 이상
Azure Blob Storage (Azure 블롭 스토리지)	모든 버전	모든 버전	모든 버전

자동 로더에서 만든 이벤트 알림 리소스 정리

자동 로더는 파일 알림 리소스를 자동으로 중단하지 않습니다. 파일 알림 리소스를 중단하려면 이전 섹션과 같이 클라우드 리소스 관리자를 사용해야 합니다. 클라우드 공급자의 UI 또는 API를 사용하여 이러한 리소스를 수동으로 삭제할 수도 있습니다.

일반적인 오류 해결 방법

이 섹션에서는 파일 알림 모드에서 자동 로더를 사용할 때 발생하는 일반적인 오류와 이를 해결하는 방법을 설명합니다.

Event Grid 구독을 만들지 못했습니다.

자동 로더를 처음 실행할 때 다음 오류 메시지가 표시되면 Event Grid는 Azure 구독에서 리소스 공급자로 등록되지 않습니다.

java.lang.RuntimeException: Failed to create event grid subscription.

Event Grid를 리소스 공급자로 등록하려면 다음을 수행합니다.

1. Azure Portal에서 구독으로 이동합니다.
2. 설정 섹션에서 리소스 공급자 클릭합니다.
3. Microsoft.EventGrid 공급자를 등록합니다.

Event Grid 구독 작업을 수행하는 데 필요한 권한 부여

자동 로더를 처음 실행할 때 다음 오류 메시지가 표시되면 기여자 역할이 Event Grid 및 스토리지 계정의 서비스 주체에 할당되었는지 확인합니다.

403 Forbidden ... does not have authorization to perform action 'Microsoft.EventGrid/eventSubscriptions/[read|write]' over scope ...

Event Grid 클라이언트가 프록시를 바이패스합니다.

Databricks Runtime 15.2 이상에서 자동 로더의 Event Grid 연결은 기본적으로 시스템 속성의 프록시 설정을 사용합니다. Databricks Runtime 13.3 LTS, 14.3 LTS 및 15.0~15.2에서는 Spark 구성 속성을 spark.databricks.cloudFiles.eventGridClient.useSystemProperties true설정하여 프록시를 사용하도록 Event Grid 연결을 수동으로 구성할 수 있습니다. 에서 Azure Databricks의 Spark 구성 속성을 설정하는 방법을 참조하세요.