Azure 데이터베이스에 대한 Data API Builder 사용 문제 해결

아티클
07/30/2024

이 문서에서는 Azure 데이터베이스에 Data API Builder를 사용할 때 발생할 수 있는 일반적인 오류에 대한 솔루션을 제공합니다.

일반 엔드포인트: HTTP 400 "잘못된 요청" 오류

다음 섹션에서는 HTTP 400 "잘못된 요청" 오류의 원인과 해결 방법을 설명합니다.

잘못된 데이터 API 작성기 엔드포인트

URL 경로 구성 요소의 기본은 데이터 API 작성기의 REST 또는 GraphQL 엔드포인트에 매핑됩니다. URL 경로 구성 요소의 기준이 데이터 API 작성기의 런타임 구성에 설정된 값과 일치하지 않는 경우 Data API Builder는 HTTP 400 "잘못된 요청" 오류를 반환합니다.

Data API Builder의 런타임 구성 섹션에서 GraphQL 및 REST 엔드포인트 runtime 에 대한 루트 경로를 구성할 수 있습니다. REST 및 GraphQL 엔드포인트에 대한 URL 경로를 시작하려면 값을 사용해야 합니다.

예를 들어 다음 구성은 REST 엔드포인트의 루트 경로 및 /graphql GraphQL 엔드포인트의 루트로 설정합니다/api.

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "...",
}

따라서 REST 및 GraphQL 엔드포인트에 대한 URL 경로의 시작 부분에서 사용해야 하는 값은 다음과 같습니다.

/api/<entity>

/graphql

참고 항목

데이터베이스 연결 기능을 사용하여 Static Web Apps에서 Data API Builder를 사용하는 경우 URL 경로는 .로 /data-api시작합니다. 이 값 이후에 원하는 엔드포인트의 값을 추가할 수 있습니다. 예를 들어 /data-api/api/<entity> REST 및 /data-api/graphql GraphQL의 경우입니다.

Static Web Apps 데이터베이스 연결 구성 문제

Static Web Apps 데이터베이스 연결 기능과 함께 데이터 API 작성기를 사용하는 경우 응답 본문에 "응답 상태 코드가 성공을 나타내지 않음: 400(잘못된 요청)" 오류가 발생합니다.

{"Message":"{\u0022Message\u0022:\u0022Response status code does not indicate success: 400 (Bad Request).\u0022,\u0022ActivityId\u0022:\u0022<GUID>\u0022}","ActivityId":"<GUID>"}

이 오류는 데이터베이스를 연결할 때 제공한 구성에 문제가 있음을 나타낼 수 있습니다.

이 문제를 해결하려면 다음 단계를 따릅니다.

Azure Data Studio 또는 SSMS(SQL Server Management Studio)와 같은 도구에서 데이터베이스 자격 증명이 유효한지 확인합니다.
연결된 데이터베이스의 연결 해제/다시 연결

여전히 오류가 발생하는 경우 Azure Database 리소스의 네트워킹 페이지에서 예외에 대해 Azure 서비스 및 리소스가 이 서버에 액세스하도록 허용을 선택해야 합니다. 이 옵션은 다른 고객의 구독 연결을 포함하여 Azure 서비스 또는 자산에 할당된 IP 주소의 연결을 허용하도록 방화벽을 구성합니다.

REST 엔드포인트: HTTP 404 "찾을 수 없음" 오류

요청된 URL이 엔터티와 연결되지 않은 경로를 가리키는 경우 HTTP 404 오류가 반환됩니다. 기본적으로 엔터티의 이름도 경로 이름입니다. 예를 들어 다음 예제와 같이 구성 파일에서 샘플 Todo 엔터티를 구성하는 경우

"Todo": {
      "source": "dbo.todos",
      "...": "..."
    }

그런 다음, Todo 다음 경로를 통해 엔터티에 연결할 수 있습니다.

/<rest-route>/Todo

다음 예제와 같이 엔터티 구성todo에서 속성을 지정할 rest.path 경우

"Todo": {
    "source": "dbo.todos",
    "rest": {
      "path": "todo"
    },
    "...": "..."
  }

그런 다음 엔터티의 Todo URL 경로는 todo런타임 구성에 정의된 정확한 값과 일치하는 모든 소문자를 포함합니다.

/<rest-route>/todo

GraphQL 엔드포인트: HTTP 400 "잘못된 요청" 오류

GraphQL 요청은 GraphQL 요청이 잘못 생성될 때마다 HTTP 400 "잘못된 요청" 오류가 발생합니다. 기존 엔터티 필드가 아니거나 철자가 잘못된 엔터티 이름 때문일 수 있습니다. 데이터 API 작성기에서는 응답 페이로드에서 설명 오류 및 오류 세부 정보를 반환합니다.

GraphQL 엔드포인트에 요청을 보내 GET 면 반환된 오류의 응답 본문에 "매개 변수 쿼리 또는 매개 변수 ID를 설정해야 합니다."가 표시됩니다. HTTP POST를 사용하여 GraphQL 요청을 보내야 합니다.

GraphQL 엔드포인트: HTTP 404 "찾을 수 없음" 오류

HTTP POST 메서드를 사용하여 GraphQL 요청이 구성된 GraphQL 엔드포인트로 전송되는지 확인합니다. 기본적으로 GraphQL 엔드포인트 경로는 .입니다 /graphql.

GraphQL 엔드포인트: "개체 유형 쿼리가 유효하려면 하나 이상의 필드를 정의해야 합니다." 오류

데이터 API 작성기 시작 시 런타임 구성에 따라 GraphQL 스키마를 생성하지 못하면 다음과 같은 오류 메시지가 표시됩니다.

개체 형식 쿼리는 유효하려면 하나 이상의 필드를 정의해야 합니다.

GraphQL 사양을 사용하려면 GraphQL 스키마에 하나 Query 이상의 개체를 정의해야 합니다. 런타임 구성이 다음 조건 중 하나를 충족하는지 확인해야 합니다.

작업은 read 하나 이상의 GraphQL 사용 엔터티에 대해 정의됩니다. GraphQL은 기본적으로 엔터티에서 사용하도록 설정되므로 이 완화를 구성된 {"graphql": false}엔터티에 적용하지 않도록 합니다.
저장 프로시저만 노출하는 경우 기본 저장 프로시저 GraphQL 작업 유형을 mutation재정의하는 하나 이상의 저장 프로시저 엔터티를 정의 { "graphql": { "operation": query" } } 합니다.

데이터를 읽고 수정하지 않는 저장 프로시저가 하나 이상 있어야 합니다. 그렇지 않으면 스키마의 빈 query 필드로 인해 GraphQL 스키마 생성이 실패합니다.

GraphQL 엔드포인트: GraphQL 엔드포인트에서 인트로펙션이 작동하지 않음

GraphQL을 지원하는 도구는 일반적으로 추가 설정 없이 GraphQL 스키마 내성 검사를 활용합니다. 구성 섹션에서 런타임 구성 속성을 allow-introspection 설정해야 합니다 true runtime.graphql . 예시:

"runtime": {
    "...": "...",
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

GraphQL 엔드포인트: "operation_name> 변경 작업이 <성공했지만 현재 사용자는 읽기 권한 부족으로 인해 응답을 볼 수 없습니다." 오류

유효한 응답을 받으려면 GraphQL 변형 작업의 경우 만들기, 업데이트 및 삭제와 같은 각 변경 작업 유형 외에도 읽기 권한을 구성해야 합니다. 오류에서 알 수 있듯이 데이터베이스 계층에서 변경 작업(만들기/업데이트/삭제)이 성공했지만 읽기 권한이 부족하여 Data API 작성기에서 오류 메시지를 반환했습니다. 따라서 "익명" 역할 또는 변형 작업을 실행하려는 역할에서 읽기 권한을 구성해야 합니다.

일반 오류: 요청에 의해 반환된 HTTP 500 오류

HTTP 500 오류는 데이터 API 작성기에서 백 엔드 데이터베이스에서 제대로 작동할 수 없음을 나타냅니다. 다음 조건을 충족해야 합니다.

데이터 API 작성기에서는 구성된 데이터베이스에 계속 연결할 수 있습니다.
데이터 API 작성기에서 사용하는 데이터베이스 개체는 여전히 사용할 수 있고 액세스할 수 있습니다.

데이터 API 작성기에서 응답에서 특정 데이터베이스 오류를 반환할 수 있도록 하려면 구성 속성을 다음으로 development설정합니다runtime.host.mode.

"runtime": {
    [...]
    "host": {
        "mode": "development",
        [...]
    }
}

기본적으로 Data API Builder는 이 production설정으로 runtime.host.mode 실행됩니다. 모드에서 production 데이터 API 작성기에서는 응답 페이로드에 자세한 오류를 반환하지 않습니다.

데이터 API 작성기에서는 둘 다 development production 와 모드에서 콘솔에 자세한 오류를 기록하여 문제 해결에 도움을 줍니다.

인증되지 않은 요청 및 권한 없는 요청으로 인한 일반 오류

HTTP 401 "권한 없음" 오류

HTTP 401 오류는 액세스하는 엔드포인트 및 엔터티에 인증이 필요하고 요청자가 요청에 유효한 인증 메타데이터를 제공하지 않을 때 발생합니다.

Microsoft Entra ID 인증을 사용하도록 Data API Builder를 구성하면 제공된 전달자(액세스) 토큰이 유효하지 않으면 요청 시 HTTP 401 오류가 발생합니다. 액세스 토큰은 여러 가지 이유로 유효하지 않을 수 있습니다. 다음은 몇 가지 예입니다.

액세스 토큰이 만료되었습니다.
액세스 토큰은 데이터 API 작성기 API(잘못된 액세스 토큰 대상)를 위한 것이 아닙니다.
액세스 토큰은 필요한 기관(잘못된 액세스 토큰 발급자)에 의해 만들어지지 않습니다.

이 오류를 해결하려면 다음 조건을 충족해야 합니다.

런타임 구성 섹션에 issuer 정의된 authentication 값을 사용하여 액세스 토큰을 생성합니다.
런타임 구성 섹션에 audience 정의된 값에 authentication 대한 액세스 토큰이 생성됩니다.

다음은 샘플 구성입니다.

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3"
    }
}

정의된 대상 그룹에 대한 유효한 토큰을 생성해야 합니다. Azure CLI를 사용하는 경우 매개 변수에서 대상 그룹을 지정하여 액세스 토큰을 resource 가져올 수 있습니다.

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3"

HTTP 403 "사용할 수 없음" 오류

Static Web Apps 통합 또는 Microsoft Entra ID를 사용하여 인증된 요청을 보내는 경우 HTTP 403 "사용할 수 없음" 오류가 발생할 수 있습니다. 이 오류는 구성 파일에 없는 역할을 사용하려고 했음을 나타냅니다.

이 오류가 발생하는 경우는 다음과 같습니다.

역할 이름을 지정하는 X-MS-API-ROLE HTTP 헤더는 제공하지 않습니다.

인증된 요청은 기본적으로 시스템 역할 authenticated 의 컨텍스트에서 실행되므로 이 시나리오는 비 시스템 역할(또는 authenticated anonymous아님)을 사용하는 경우에만 적용됩니다.
헤더에서 X-MS-API-ROLE 정의하는 역할은 Data API Builder의 런타임 구성 파일에서 구성되지 않습니다.
헤더에서 X-MS-API-ROLE 정의하는 역할이 액세스 토큰의 역할과 일치하지 않습니다.

예를 들어 다음 런타임 구성 파일에서 역할이 role1 정의되므로 HTTP 헤더에 X-MS-API-ROLE 값을 role1제공해야 합니다.