JavaScript용 Azure Tables 클라이언트 라이브러리 - 버전 13.3.0

Azure Tables 구조화된 NoSQL 데이터를 저장하여 스키마 없는 디자인으로 키/특성 저장소를 제공하는 클라우드 기반 서비스입니다. 테이블 스토리지는 개발자에게 Azure 클라우드의 모든 최고의 부분을 통해 유연성과 확장성을 제공합니다.

클라이언트 라이브러리를 사용하여 다음을 수행합니다.

• 테이블 만들기/삭제
• 엔터티 쿼리/만들기/읽기/업데이트/삭제

Azure Cosmos DB는 Azure Table Storage용으로 작성되었으며 다음과 같은 프리미엄 기능이 필요한 애플리케이션용 Table API를 제공합니다.

• 턴키 전역 배포.
• 전 세계 전용 처리량입니다.
• 99번째 백분위수의 대기 시간(밀리초)입니다.
• 고가용성을 보장합니다.
• 자동 보조 인덱싱.
• Azure Tables 클라이언트 라이브러리는 코드 변경 없이 Azure Table Storage 또는 Azure Cosmos DB 테이블 서비스 엔드포인트를 원활하게 대상으로 지정할 수 있습니다.

키 링크:

• 소스 코드
• NPM(패키지)
• API 참조 설명서
• 제품 설명서
• 샘플

시작

필수 구성 요소

현재 지원되는 환경:

• LTS 버전의 Node.js
• Safari, Chrome, Edge 및 Firefox의 최신 버전

이 패키지를 사용하려면 Azure 구독 및 Storage 계정 또는 Azure CosmosDB 데이터베이스 있어야 합니다.

@azure/data-tables 패키지 설치

JavaScript용 Azure Tables 클라이언트 라이브러리를 설치하는 기본 방법은 npm 패키지 관리자를 사용하는 것입니다. 터미널 창에 다음을 입력합니다.

npm install @azure/data-tables

TableServiceClient 인증

Azure Tables는 인증하는 여러 가지 방법을 지원합니다. Azure Tables 서비스와 상호 작용하려면 테이블 클라이언트의 인스턴스(예: TableServiceClient 또는 TableClient)를 만들어야 합니다. 인증에 대한 자세한 내용은 만들기 위한 샘플을 참조하세요.

참고: AAD(Azure Active Directory)는 Azure Storage 계정에 대해서만 지원됩니다.

• 공유 키 있는 Service 클라이언트
• 공유 액세스 서명 있는 Service 클라이언트
• AAD(TokenCredential) 있는 Service 클라이언트
• 공유 키 사용하여 Table 클라이언트
• 공유 액세스 서명이 있는 Table 클라이언트
• AAD(TokenCredential) 사용하여 Table 클라이언트

다음 기능, 인터페이스, 클래스 또는 함수는 Node.js

• 계정 이름 및 계정 키를 기반으로 하는 공유 키 권한 부여
  • AzureNamedKeyCredential
  • 계정 연결 문자열입니다.

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서참조하세요.

CORS

브라우저용으로 개발해야 하는 경우 스토리지 계정에 대한 CORS(원본 간 리소스 공유) 규칙을 설정해야 합니다. Azure Portal 및 Azure Storage Explorer로 이동하여 스토리지 계정을 찾고 Blob/큐/파일/테이블 서비스에 대한 새 CORS 규칙을 만듭니다.

예를 들어 디버깅을 위해 다음 CORS 설정을 만들 수 있습니다. 그러나 프로덕션 환경의 요구 사항에 따라 설정을 신중하게 사용자 지정하세요.

• 허용된 원본: *
• 허용되는 동사: DELETE, GET, HEAD,MERGE,POST,OPTIONS,PUT
• 허용되는 헤더: *
• 노출된 헤더: *
• 최대 사용 기간(초): 86400

주요 개념

• TableServiceClient - 테이블 만들기, 나열 및 삭제와 같은 Table Service 수준에서 상호 작용하는 함수를 제공하는 클라이언트

• TableClient - 테이블 내에서 엔터티 만들기, 나열 및 삭제와 같은 엔터티 수준에서 상호 작용하는 함수를 제공하는 클라이언트입니다.

• Table - 테이블은 데이터를 엔터티 컬렉션으로 저장합니다.

• Entity - 엔터티는 행과 유사합니다. 엔터티에는 기본 키와 속성 집합이 있습니다. 속성은 열과 유사한 이름, 형식화된 값 쌍입니다.

Table Service의 일반적인 용도는 다음과 같습니다.

• 웹 규모 애플리케이션을 처리할 수 있는 구조화된 데이터의 TB 저장
• 복잡한 조인, 외장 키 또는 저장 프로시저가 필요하지 않고 빠른 액세스를 위해 정규화 해제할 수 있는 데이터 세트 저장
• 클러스터형 인덱스로 신속하게 데이터 쿼리
• OData 프로토콜 필터 식을 사용하여 데이터 액세스

예제

• 패키지 가져오기
• 테이블 서비스 클라이언트 만들기
  • 계정 테이블 나열
  • 새 테이블 만들기
• 테이블 클라이언트 만들기
  • 테이블 엔터티 나열
  • 새 엔터티를 만들고 테이블에 추가

패키지 가져오기

클라이언트를 사용하려면 파일에서 패키지를 가져옵니다.

const AzureTables = require("@azure/data-tables");

또는 필요한 형식만 선택적으로 가져옵니다.

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

Table Service 클라이언트 만들기

TableServiceClient 테이블 서비스에 대한 URL과 액세스 자격 증명이 필요합니다. 또한 필요에 따라 options 매개 변수의 일부 설정을 허용합니다.

AzureNamedKeyCredential을 사용하여 TableServiceClient

계정 이름 및 계정 키를 인수로 전달하여 AzureNamedKeyCredential 사용하여 TableServiceClient 인스턴스화할 수 있습니다. (계정 이름 및 계정 키는 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TokenCredential(AAD)을 사용하여 TableServiceClient

Azure Tables는 스토리지 엔드포인트를 대상으로 할 때 Table Service에 대한 요청의 ID 기반 인증을 위해 Azure AD(Azure Active Directory)와 통합됩니다. Azure AD를 사용하면 RBAC(역할 기반 액세스 제어)를 사용하여 사용자, 그룹 또는 애플리케이션에 Azure Table 리소스에 대한 액세스 권한을 부여할 수 있습니다.

TokenCredential사용하여 테이블 리소스에 액세스하려면 인증된 ID에 "Storage Table Data Contributor" 또는 "Storage Table Data Reader" 역할이 있어야 합니다.

@azure/identity 패키지를 사용하면 개발 및 프로덕션 환경 모두에서 요청에 원활하게 권한을 부여할 수 있습니다. Azure Storage의 Azure AD 통합에 대한 자세한 내용은 Azure.Identity 추가 정보 참조하세요.

const { TableServiceClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";

const clientWithAAD = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

SAS 토큰을 사용하여 TableServiceClient

또한 SAS(공유 액세스 서명)를 사용하여 TableServiceClient 인스턴스화할 수 있습니다. Azure Portal에서 SAS 토큰을 가져올 수 있습니다.

const { TableServiceClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  new AzureSASCredential(sas)
);

계정의 테이블 나열

listTables 함수를 호출하는 TableServiceClient 인스턴스를 통해 계정 내의 테이블을 나열할 수 있습니다. 이 함수는 for-await-of 사용하여 사용할 수 있는 PageableAsyncIterator 반환합니다.

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tablesIter = serviceClient.listTables();
  let i = 1;
  for await (const table of tablesIter) {
    console.log(`Table${i}: ${table.name}`);
    i++;
    // Output:
    // Table1: testTable1
    // Table1: testTable2
    // Table1: testTable3
    // Table1: testTable4
    // Table1: testTable5
  }
}

main();

새 테이블 만들기

createTable 함수를 호출하는 TableServiceClient 인스턴스를 통해 테이블을 만들 수 있습니다. 이 함수는 테이블의 이름을 매개 변수로 만듭니다. 테이블이 이미 있는 경우 createTable 오류를 throw하지 않습니다.

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable`;
  // If the table 'newTable' already exists, createTable doesn't throw
  await serviceClient.createTable(tableName);
}

main();

다음은 테이블을 만들 때 테이블이 이미 있는지 테스트하는 방법을 보여 주는 샘플입니다.

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

테이블 클라이언트 만들기

TableClient TableClient 테이블 이름을 매개 변수로 사용하는 차이점이 있는 TableServiceClient 유사한 방식으로 만들어집니다.

AzureNamedKeyCredential 사용하여 TableClient

계정 이름 및 계정 키를 인수로 전달하여 AzureNamedKeyCredential 사용하여 TableClient 인스턴스화할 수 있습니다. (계정 이름 및 계정 키는 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

TokenCredential TableClient(Azure Active Directory)

Azure Tables는 스토리지 엔드포인트를 대상으로 할 때 Table Service에 대한 요청의 ID 기반 인증을 위해 Azure AD(Azure Active Directory)와 통합됩니다. Azure AD를 사용하면 RBAC(역할 기반 액세스 제어)를 사용하여 사용자, 그룹 또는 애플리케이션에 Azure Table 리소스에 대한 액세스 권한을 부여할 수 있습니다.

TokenCredential사용하여 테이블 리소스에 액세스하려면 인증된 ID에 "Storage Table Data Contributor" 또는 "Storage Table Data Reader" 역할이 있어야 합니다.

@azure/identity 패키지를 사용하면 개발 및 프로덕션 환경 모두에서 요청에 원활하게 권한을 부여할 수 있습니다. Azure Storage의 Azure AD 통합에 대한 자세한 내용은 Azure.Identity 추가 정보 참조하세요.

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

SAS 토큰을 사용하여 TableClient

SAS(공유 액세스 서명)를 사용하여 TableClient 인스턴스화할 수 있습니다. Azure Portal에서 SAS 토큰을 가져올 수 있습니다.

const { TableClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas)
);

TokenCredential(AAD)을 사용하여 TableClient

Azure Tables는 스토리지 엔드포인트를 대상으로 할 때 Table Service에 대한 요청의 ID 기반 인증을 위해 Azure AD(Azure Active Directory)와 통합됩니다. Azure AD를 사용하면 RBAC(역할 기반 액세스 제어)를 사용하여 사용자, 그룹 또는 애플리케이션에 Azure Table 리소스에 대한 액세스 권한을 부여할 수 있습니다.

TokenCredential사용하여 테이블 리소스에 액세스하려면 인증된 ID에 "Storage Table Data Contributor" 또는 "Storage Table Data Reader" 역할이 있어야 합니다.

@azure/identity 패키지를 사용하면 개발 및 프로덕션 환경 모두에서 요청에 원활하게 권한을 부여할 수 있습니다. Azure Storage의 Azure AD 통합에 대한 자세한 내용은 Azure.Identity 추가 정보 참조하세요.

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

테이블의 엔터티 나열

listEntities 함수를 호출하는 TableClient 인스턴스를 통해 테이블 내의 엔터티를 나열할 수 있습니다. 이 함수는 for-await-of 사용하여 사용할 수 있는 PageableAsyncIterator 반환합니다.

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const entitiesIter = client.listEntities();
  let i = 1;
  for await (const entity of entitiesIter) {
    console.log(`Entity${i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
    i++;
    // Output:
    // Entity1: PartitionKey: P1 RowKey: R1
    // Entity2: PartitionKey: P2 RowKey: R2
    // Entity3: PartitionKey: P3 RowKey: R3
    // Entity4: PartitionKey: P4 RowKey: R4
  }
}

main();

새 엔터티를 만들고 테이블에 추가합니다.

createEntity 함수를 호출하는 TableClient 인스턴스를 통해 테이블에 새 엔터티를 만들 수 있습니다. 이 함수는 엔터티를 매개 변수로 삽입합니다. 엔터티에는 partitionKey 및 rowKey포함되어야 합니다.

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const testEntity = {
    partitionKey: "P1",
    rowKey: "R1",
    foo: "foo",
    bar: 123
  };
  await client.createEntity(testEntity);
}

main();

Azurite 및 Storage 에뮬레이터

Azure Tables 클라이언트 SDK는 Azure Storage 및 Tables API 호환 서버 에뮬레이터인 Azurite에서도 작동합니다. 사용을 시작하는 방법은 (Azurite 리포지토리)를 참조하세요.

연결 문자열 바로 가기를 사용하여 Azurite에 연결

애플리케이션에서 Azurite에 연결하는 가장 쉬운 방법은 바로 가기 UseDevelopmentStorage=true참조하는 연결 문자열을 구성하는 것입니다. 바로 가기는 각 Azure Storage 서비스의 계정 이름, 계정 키 및 에뮬레이터 엔드포인트를 지정하는 에뮬레이터의 전체 연결 문자열과 같습니다(더 많은참조). 이 바로 가기를 사용하여 Azure Tables 클라이언트 SDK는 기본 연결 문자열을 설정하며 클라이언트 옵션에서 allowInsecureConnection.

import { TableClient } from "@azure/data-tables";

const connectionString = "UseDevelopmentStorage=true";
const client = TableClient.fromConnectionString(connectionString, "myTable");

연결 문자열 바로 가기 없이 Azurite에 연결

서비스 URL 및 AzureNamedKeyCredential 또는 사용자 지정 연결 문자열을 지정하여 연결 문자열 바로 가기를 사용하지 않고도 azurite에 수동으로 연결할 수 있습니다. 그러나 Azurite가 http 엔드포인트에서 실행되는 경우 allowInsecureConnection 수동으로 설정해야 합니다.

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

const client = new TableClient(
  "<Azurite-http-table-endpoint>",
  "myTable",
  new AzureNamedKeyCredential("<Azurite-account-name>", "<Azurite-account-key>"),
  { allowInsecureConnection: true }
);

문제 해결

일반

Javascript/Typescript SDK를 사용하여 Tables 서비스와 상호 작용하는 경우 서비스에서 반환된 오류는 REST API 요청에 대해 반환된 것과 동일한 HTTP 상태 코드에 해당합니다. Storage Table Service 오류 코드

로깅

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 @azure/loggersetLogLevel 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

다음 단계

추가 코드 샘플 출시 예정 문제#10531

기여

이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 귀하가 귀하의 기여를 사용할 권리를 부여할 권리가 있음을 선언하는 CLA(기여자 사용권 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com방문하세요.

끌어오기 요청을 제출하면 CLA 봇은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 주석). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 이 작업을 수행해야 합니다.

이 프로젝트는 Microsoft 오픈 소스 행동 강령채택했습니다. 자세한 내용은 행동 강령 FAQ 참조하거나 추가 질문이나 의견을 opencode@microsoft.com 문의하세요.

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.