연습 - 입력 바인딩을 사용하여 데이터 읽기 - Training

20분

책갈피 조회 서비스를 만들려 한다고 가정해 봅시다. 처음에는 서비스가 읽기 전용입니다. 사용자가 항목을 찾으려는 경우 항목의 ID와 함께 요청을 보내면 함수에서 URL을 반환합니다. 다음 순서도는 논리 흐름을 보여 줍니다.

사용자가 텍스트를 사용하여 요청을 보내면 책갈피 찾기 함수가 해당 텍스트를 키나 ID로 사용하여 데이터베이스에서 책갈피가 포함된 항목을 찾습니다. 시스템에서 항목을 찾았는지 여부를 나타내는 결과를 반환합니다.

Azure 함수는 책갈피 ID가 있는 요청을 받으면 먼저 요청이 유효한지 확인합니다. 유효하지 않으면 오류 응답이 생성됩니다. 요청이 유효하면 함수는 책갈피 ID가 Azure Cosmos DB 데이터베이스에 있는지 확인합니다. 존재하지 않는 경우 오류 응답이 생성됩니다. 책갈피 ID가 있으면 성공 응답이 생성됩니다.

특정 위치에 데이터를 저장해야 합니다. 이전 순서도에서 데이터 저장소는 Azure Cosmos DB 인스턴스입니다. 하지만 어떻게 함수에서 데이터베이스에 연결하고 데이터를 읽습니까? 함수 부분에서는 해당 작업을 위해 입력 바인딩을 구성합니다. Azure Portal을 통해 간단하게 입력 바인딩을 구성할 수 있습니다. 곧 살펴보겠지만 코드를 작성하거나 스토리지 연결을 열 필요가 없습니다. Azure Functions 런타임 및 바인딩이 이러한 작업을 담당합니다.

Azure Cosmos DB 계정 만들기

참고

이 연습은 Azure Cosmos DB에 대한 자습서가 아닙니다. 더 자세히 알고 싶으면 이 모듈의 마지막에 있는 Azure Cosmos DB에 관한 전체 학습 경로를 참조하세요.

데이터베이스 계정 만들기

데이터베이스 계정은 하나 이상의 데이터베이스를 관리하기 위한 컨테이너입니다. 데이터베이스를 만들려면 먼저 데이터베이스 계정을 만들어야 합니다.

Azure Portal 리소스 메뉴 또는 홈페이지에서 리소스 만들기를 선택합니다. 리소스 만들기 창이 나타납니다.
리소스 만들기 메뉴에서 데이터베이스를 선택한 다음, Azure Cosmos DB를 검색하여 선택합니다. 워크로드에 가장 적합한 API 창이 나타납니다.
Azure Cosmos DB for NoSQL 옵션에서 Cosmos DB 트리거와 입출력 바인딩을 만들 수 있도록 만들기를 선택합니다. Azure Cosmos DB 계정 만들기 - Azure Cosmos DB for NoSQL 창이 나타납니다.

기본 탭에서 각 설정에 다음 값을 입력합니다.

설정	값	설명
프로젝트 세부 정보
구독	컨시어지 구독	샌드박스의 리소스와 함께 작동하는 Azure 구독입니다.
리소스 그룹	드롭다운 목록에서 [샌드박스 리소스 그룹 이름]을 선택합니다.	샌드박스의 리소스 그룹입니다.
인스턴스 세부 정보
계정 이름	`globally unique name`	Azure Cosmos DB 계정에 대해 고유하지만 식별 가능한 이름을 입력합니다. `documents.azure.com`이 제공하는 이름에 추가됩니다. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
위치	`region`	가장 가까운 지역을 선택합니다.

나머지 설정에 기본값을 적용하고 검토 + 만들기를 선택하여 입력을 확인합니다. 유효성 검사 성공 알림이 나타납니다.
만들기를 선택하여 데이터베이스 계정을 프로비저닝하고 배포합니다.
배포에 다소 시간이 걸릴 수 있습니다. 진행하기 전에 알림 허브에 배포 성공 메시지가 표시되기를 기다립니다.
리소스로 이동을 선택하여 포털에서 데이터베이스 계정으로 이동합니다. Azure Cosmos DB 계정의 빠른 시작 창이 나타납니다.

다음으로 컨테이너를 추가한 후 Azure Cosmos DB 계정에 데이터베이스를 추가합니다.

컨테이너 추가

Azure Cosmos DB에서 컨테이너는 다양한 사용자 생성 엔터티(항목이라고도 함)를 저장하는 데 사용됩니다. 책갈피라는 컨테이너를 만듭니다.

Data Explorer 도구를 사용하여 데이터베이스와 컨테이너를 만들어보겠습니다.

여러분의 Azure Cosmos DB 계정 메뉴에서 데이터 탐색기를 선택합니다. Cosmos DB 계정의 Data Explorer 창이 나타납니다.
새 컨테이너 상자를 선택합니다. 새 컨테이너 창이 나타납니다. 이를 보려면 스크롤해야 할 수도 있습니다.

각 설정에 다음 값을 입력합니다.

설정	값	설명
데이터베이스 ID	새로 만들기를 선택하고 데이터베이스 ID로 func-io-learn-db를 입력합니다.	데이터베이스 이름은 1~255자일 수 있으며 /, \, #, ? 또는 후행 공백을 포함할 수 없습니다. 원하는 대로 입력할 수 있지만, 이 모듈에서는 func-io-learn-db를 사용합니다.
데이터베이스 최대 RU/s	4000	기본 처리량인 4000RU/s(초당 요청 단위)를 적용합니다. 대기 시간을 줄이기 위해 나중에 성능을 스케일 업할 수 있습니다.
컨테이너 ID	책갈피	컨테이너 ID에는 데이터베이스 이름과 동일한 문자 요구 사항이 적용됩니다. 이 모듈에서는 책갈피를 사용합니다.
파티션 키	/id	파티션 키는 Azure Cosmos DB 컬렉션의 문서를 논리 데이터 파티션에 분산하는 방법을 지정합니다. 이 모듈에서는 데이터베이스 성능 문제를 고려하지 않으므로 편의상 여기서는 파티션 키 설정을 사용하겠습니다. Azure Cosmos DB 파티션 키 전략에 대해 자세히 알아보려면 Microsoft Learn Azure Cosmos DB 모듈을 살펴보세요.

다른 모든 설정에 기본값을 적용합니다.

창 맨 아래로 스크롤하여 확인을 선택합니다. 데이터베이스와 컨테이너가 빌드될 때까지 몇 분 정도 기다립니다.

완료되면 데이터 탐색기에서 NOSQL API 아래 데이터에 func-io-learn-db를 표시합니다.
func-io-learn-db를 선택하여 확장합니다. func-io-learn-db 데이터베이스에는 배율, 책갈피 등 여러 자식 멤버가 포함되어 있습니다.
책갈피 컨테이너를 확장하면 몇 개의 자식 멤버로 미리 채워져 있는 것을 볼 수 있습니다.

다음 작업에서는 책갈피 컨테이너에 항목이라고도 하는 몇몇 데이터를 추가합니다.

테스트 데이터 추가

책갈피 컨테이너에 데이터를 추가하려고 합니다. 데이터 탐색기를 사용하여 각 항목의 ID와 URL을 저장합니다.

func-io-learn-db 데이터베이스와 책갈피 컨테이너를 차례로 확장하고 항목을 선택합니다. 항목 탭이 나타납니다.
명령 모음에서 새 항목을 선택합니다.

새 항목의 기본 코드를 다음 JSON 코드로 바꿉니다.

{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}

명령 모음에서 저장을 선택합니다.

추가한 두 줄보다 많은 속성이 표시됩니다. 모두 밑줄((_rid, _self, _etag, _attachments, _ts))로 시작합니다. 다음 표에 설명된 이러한 속성은 컨테이너에 추가하는 항목을 관리하는 데 도움이 되도록 시스템에서 생성됩니다.

속성	Description
`_rid`	리소스 ID는 리소스 모델의 리소스 스택에 따라 계층적인 고유 식별자입니다. 항목 리소스의 배치와 탐색을 위해 내부적으로 사용됩니다.
`_self`	리소스에 대한 고유의 주소 지정 가능 URI입니다.
`_etag`	낙관적 동시성 제어에 필요합니다.
`_attachments`	첨부 파일 리소스에 대한 주소 지정 가능 경로입니다.
`_ts`	이 리소스의 마지막 업데이트에 대한 타임 스탬프입니다.

책갈피 컨테이너에 몇 가지 항목을 추가해 보겠습니다. 명령 모음에서 새 항목을 선택합니다. 다음과 같은 콘텐츠로 4개 항목을 더 만듭니다. 새 항목을 선택한 다음, 각 새 항목을 복사하여 붙여넣은 후 저장을 선택하여 항목을 추가합니다. 각 항목이 항목 목록에 추가되는 방식을 확인합니다.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
책갈피 데이터 입력을 마치면 컨테이너는 다음 이미지와 같은 모양입니다.

책갈피 컨테이너에 항목이 5개 있습니다. 이 시나리오에서는 “id=docs”와 함께 요청이 도착하면 책갈피 컨테이너에서 해당 ID를 조회하고 https://learn.microsoft.com/azure URL을 반환합니다. 책갈피 컨테이너의 값을 조회하는 Azure 함수를 만들어 보겠습니다.

함수 만들기

이전 단원에서 만든 함수 앱으로 이동합니다. 리소스 메뉴에서 홈을 선택하고 최신 리소스 섹션에서 함수 앱(유형은 함수 앱)을 확인합니다. 함수 앱을 선택합니다. 함수 앱 창이 나타납니다.
개요 페이지의 함수 탭에는 HttpTrigger1 함수가 하나 있어야 합니다.
다른 함수를 만들어 보겠습니다. 함수 탭에서 만들기 선택합니다. 지원되는 트리거의 템플릿이 나열되는 함수 만들기 창이 나타납니다.
템플릿 선택 섹션에서 HTTP 트리거를 선택합니다.
모든 기본 설정을 적용하고 만들기를 선택하여 함수를 만듭니다.

HttpTrigger2 함수의 개요 창이 나타납니다.

함수 확인

새 함수를 테스트하여 지금까지 수행한 작업을 확인할 수 있습니다.

명령 모음에서 함수 URL 가져오기를 선택합니다. 함수 URL 가져오기 대화 상자가 나타납니다.
드롭다운 목록에서 기본값(함수 키)을 선택하고 ‘클립보드로 복사’ 아이콘을 선택하고 확인을 선택합니다.
복사한 함수 URL을 새 브라우저 탭의 주소 표시줄에 붙여넣습니다. URL의 끝에 쿼리 문자열 값 &name=<your name>을 추가합니다. <your name>을 사용자의 이름으로 바꾸고 Enter 키를 누릅니다. Azure 함수가 브라우저에서 맞춤형 응답을 반환합니다.

이제 기본 함수가 작동하므로 Azure Cosmos DB 또는 시나리오의 책갈피 컨테이너로부터 데이터 읽기를 살펴보겠습니다.

Azure Cosmos DB 입력 바인딩 추가

데이터베이스에서 데이터를 읽으려면 입력 바인딩을 정의해야 합니다. 여기서 보듯, 몇 단계 만에 데이터베이스와 통신할 수 있는 바인딩을 구성할 수 있습니다.

Azure Portal의 왼쪽에 있는 HttpTrigger2 함수 메뉴에서 통합을 선택합니다. 함수의 통합 창이 나타납니다.

HTTP 출력 바인딩을 사용하여 HTTP 트리거 요청을 만든 템플릿을 사용했습니다. Azure Cosmos DB 입력 바인딩을 추가해 보겠습니다.
입력 상자에서 입력 추가를 선택합니다. 입력 만들기 창이 나타납니다.
바인딩 형식 드롭다운 목록에서 Azure Cosmos DB를 선택합니다.
Azure Cosmos DB 세부 정보 섹션의 Cosmos DB 계정 연결 설정에서 새로 만들기 링크를 선택합니다. 새 Cosmos DB 연결 대화 상자가 나타납니다.

Microsoft.Azure.WebJobs.Extensions.CosmosDB 확장을 설치하라는 메시지가 나타나면 설치를 선택하고 완료될 때까지 기다립니다.
기본적으로 Azure는 이전에 만든 Azure Cosmos DB 계정을 인식합니다. 확인을 선택하여 데이터베이스에 연결을 설정합니다. 데이터베이스 계정에 ‘새’ 연결이 구성되고 Cosmos DB 계정 연결 필드에 표시됩니다.

특정 ID로 책갈피를 조회하기 위해 쿼리 문자열에서 받은 ID를 바인딩에 연결하겠습니다.

입력 만들기 창에서 설정을 완료해 보겠습니다. 각 설정에 다음 값을 입력합니다. 각 설정의 용도를 자세히 알아보려면 해당 필드의 정보 아이콘을 선택합니다.

설정	값	설명
문서 매개 변수 이름	`bookmark`	코드에서 이 바인딩을 식별하기 위해 사용하는 이름입니다.
데이터베이스 이름	`func-io-learn-db`	작업할 데이터베이스입니다. 이 값은 설정한 데이터베이스 이름입니다.
컬렉션 이름	`Bookmarks`	데이터를 읽는 대상 컬렉션입니다. 이 설정은 정의되었습니다.
문서 ID	`id`	‘책갈피’ Azure Cosmos DB 컨테이너를 만들 때 정의한 문서 ID를 추가합니다.
파티션 키	`/id`	‘책갈피’ Azure Cosmos DB 컬렉션을 만들 때 정의한 파티션 키를 추가합니다. 여기에 입력된 키(입력 바인딩 형식 `<key>`으로 지정됨)는 컬렉션에 있는 것과 일치해야 합니다.
SQL 쿼리(선택 사항)	비워 둠	ID를 기준으로 한 번에 한 문서만 검색합니다. 따라서 이 인스턴스에서 SQL 쿼리를 사용하는 것보다 문서 ID 설정을 통해 필터링하는 것이 더 적절합니다. 한 항목(`SELECT * from b where b.ID = id`)을 반환하는 SQL 쿼리를 만들 수 있습니다. 이 쿼리는 실제로 문서를 반환하지만 문서 컬렉션 안에서 반환합니다. 코드가 불필요하게 컬렉션을 조작해야 합니다. 여러 문서를 가져오려면 SQL 쿼리 방법을 사용합니다.

이러한 설정을 사용하는 이유를 명확하게 설명하기 위해 특정 ID를 사용하여 책갈피를 조회하려고 하므로 함수가 쿼리 문자열에서 수신하는 문서 ID를 입력 바인딩에 연결했습니다. 이 구문을 바인딩 식이라고 합니다. 함수는 조회할 ID를 지정하기 위해 쿼리 문자열을 사용하는 HTTP 요청에 의해 트리거됩니다. ID는 컬렉션에서 고유하므로 바인딩은 0(없음) 또는 1(있음) 문서를 반환합니다.

이 입력 바인딩 구성을 저장하려면 확인을 선택합니다.

함수 구현 업데이트

이제 바인딩이 정의되어 있으므로 함수에서 사용할 수 있습니다. 방금 만든 바인딩을 구현하기 위해 두 가지 사항을 변경해야 합니다.

함수의 언어별 구현 코드를 수정합니다. 함수에 전달된 ID와 일치하는 문서가 데이터베이스에서 발견되었는지 확인해야 합니다.
쿼리 문자열에서 전달되는 매개 변수를 허용하도록 함수의 JSON 구현 코드를 수정합니다.

함수의 JavaScript 구현 코드 수정

HttpTrigger2 함수의 함수 메뉴에서 코드 + 테스트를 선택합니다. HttpTrigger2 함수에 대한 코드 + 테스트 창이 나타납니다.

index.js 파일의 모든 코드를 다음 코드로 바꿉니다.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

명령 모음에서 저장을 선택합니다. 로그 창의 위쪽 가운데에 있는 드롭다운에서 파일 시스템 로그를 선택합니다(기본적으로 App Insights 로그 표시). Connected!를 보여 주는 로그 창이 표시됩니다.

이 코드가 수행하는 작업을 살펴보겠습니다.

들어오는 HTTP 요청은 함수를 트리거하고 id 쿼리 매개 변수는 Azure Cosmos DB 입력 바인딩으로 전달됩니다.
데이터베이스가 이 ID와 일치하는 문서를 찾는 경우 bookmark 매개 변수가 찾은 문서로 설정됩니다.

이 예제에서 코드는 데이터베이스의 해당 문서에 있는 URL 값을 포함하는 응답을 생성합니다.
이 키와 일치하는 문서가 없는 경우 요청이 이 상황을 사용자에게 알리는 페이로드와 상태 코드로 응답합니다.

함수의 JSON 구현 코드 수정

<functionapp> \ HttpTrigger2 \ 경로의 드롭다운 목록에서 function.json을 선택합니다.

{id}의 매개 변수를 허용하도록 id 및 partitionKey의 값을 수정합니다. function.json 코드는 다음 예제와 유사합니다. 여기서 your-database는 Cosmos DB 데이터베이스의 이름으로 바뀝니다.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "connection": "your-database_DOCUMENTDB",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

명령 모음에서 저장을 선택합니다.

함수의 PowerShell 구현 코드 수정

HttpTrigger2 함수의 함수 메뉴에서 코드 + 테스트를 선택합니다. HttpTrigger2 함수에 대한 코드 + 테스트 창이 나타나고 run.ps1 파일을 표시합니다.

run.ps1 파일의 모든 코드를 다음 코드로 바꿉니다.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

명령 모음에서 저장을 선택합니다. 로그 창의 위쪽 가운데에 있는 드롭다운에서 파일 시스템 로그를 선택합니다(기본적으로 App Insights 로그 표시). Connected!를 보여 주는 로그 창이 표시됩니다.

이 코드가 수행하는 작업을 살펴보겠습니다.

들어오는 HTTP 요청은 함수를 트리거하고 id 쿼리 매개 변수는 Azure Cosmos DB 입력 바인딩으로 전달됩니다.
데이터베이스가 이 ID와 일치하는 문서를 찾는 경우 bookmark 매개 변수가 찾은 문서로 설정됩니다.

이 예제에서 코드는 데이터베이스의 해당 문서에 있는 URL 값을 포함하는 응답을 생성합니다.
이 키와 일치하는 문서가 없는 경우 요청이 이 상황을 사용자에게 알리는 페이로드와 상태 코드로 응답합니다.

함수의 JSON 구현 코드 수정

<functionapp> \ HttpTrigger2 \ 경로의 드롭다운 목록에서 function.json을 선택합니다.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

명령 모음에서 저장을 선택합니다.

사용해 보기

HttpTrigger2 함수에 대한 코드 + 테스트 창을 보고 있어야 합니다.
명령 모음에서 함수 URL 가져오기를 선택합니다. 함수 URL 가져오기 대화 상자가 나타납니다.
키 드롭다운 목록의 함수 키 아래에서 기본값을 선택한 다음, URL 끝에 있는 클립보드에 복사 아이콘을 선택합니다.
복사한 함수 키를 새 브라우저 탭의 주소 표시줄에 붙여넣은 다음 URL의 끝에 쿼리 문자열 값 &id=docs를 추가합니다. 결과 URL은 다음 예제와 유사합니다.

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Enter 키를 눌러 요청을 실행합니다. 함수에서 반환된 응답은 다음 예제와 유사합니다.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
&id=docs를 &id=missing으로 바꾸고 Enter 키를 눌러 응답을 관찰합니다. 책갈피를 5개 정의하고, 요청한 책갈피가 없는 경우 의미 있는 오류 응답을 만들었습니다.

이 단원에서는 Azure Cosmos DB 데이터베이스에서 읽어오는 첫 번째 입력 바인딩을 수동으로 만들었습니다. 데이터베이스를 검색하고 데이터를 읽기 위해 작성한 코드 크기가 바인딩 덕분에 최소화되었습니다. 바인딩 구성 작업은 대부분 선언적으로 이루어지며 플랫폼이 나머지를 처리합니다.

다음 단원에서는 Azure Cosmos DB 출력 바인딩을 통해 책갈피 컬렉션에 다른 데이터를 추가합니다.

계속

연습 - 입력 바인딩을 사용하여 데이터 읽기

Azure Cosmos DB 계정 만들기

데이터베이스 계정 만들기

컨테이너 추가

테스트 데이터 추가

함수 만들기

함수 확인

Azure Cosmos DB 입력 바인딩 추가

함수 구현 업데이트

함수의 JavaScript 구현 코드 수정

함수의 JSON 구현 코드 수정

함수의 PowerShell 구현 코드 수정

함수의 JSON 구현 코드 수정

사용해 보기

피드백