Blog

Azure API 사용법

Ashley Innocent

Ashley Innocent

24 March 2026

Azure API 사용법

요약 (TL;DR)

Azure API를 사용하면 Microsoft의 클라우드 서비스(저장소, 컴퓨팅, 데이터베이스, AI 등)에 프로그래밍 방식으로 액세스할 수 있습니다. Azure Active Directory (Entra ID)를 사용하여 인증하고, 액세스 토큰을 받은 다음, REST 엔드포인트를 호출합니다. 테스트 및 문서화를 위해 Apidog를 사용하여 API 호출을 저장하고, 스키마에 따라 응답을 검증하며, 팀과 컬렉션을 공유할 수 있습니다.

서론

Microsoft Azure는 200개 이상의 서비스를 제공합니다. 각 서비스는 API를 가지고 있습니다. 대부분의 개발자는 파일용 Azure Blob Storage, 서버리스용 Azure Functions, LLM용 Azure OpenAI 등 그 중 몇 가지는 사용해 볼 것입니다.

문제점은 무엇일까요? Azure의 문서는 방대하고 산재해 있습니다. 올바른 엔드포인트를 찾고, 인증 방식을 알아내고, 요청이 401 Unauthorized를 반환하는 이유를 디버깅하는 데 몇 시간을 보낼 수도 있습니다.

이 가이드는 실제로 사용하게 될 API에 초점을 맞춥니다. 200개의 서비스가 아닌, 대부분의 애플리케이션을 구동하는 5~10가지 서비스에 대해서입니다. 인증 패턴, 일반적인 문제점, 그리고 배포 전에 Azure 통합을 테스트하는 방법을 배우게 될 것입니다.

💡
Azure API를 기반으로 개발하는 경우, Apidog는 이러한 통합을 설계, 테스트 및 문서화하는 데 도움을 줍니다. Azure API 호출을 컬렉션으로 저장하고, 다양한 구독에 대한 환경 변수를 추가하며, 응답이 예상 스키마와 일치하는지 검증할 수 있습니다. 이는 구성 오류가 프로덕션에 도달하기 전에 잡아냅니다.

버튼

Apidog로 Azure API 테스트 - 무료

이 가이드를 마치면 다음을 할 수 있게 됩니다:

인증 문제 (그리고 해결 방법)

모든 Azure API 호출에는 인증이 필요합니다. 이를 잘못 설정하면 다른 모든 것이 실패합니다. 대부분의 개발자가 여기서 어려움을 겪습니다.

Azure Active Directory / Microsoft Entra ID

Azure는 API 인증에 OAuth 2.0을 사용합니다. 사용자 이름과 비밀번호를 보내는 대신, 사용자가 누구이며 무엇을 할 수 있는지 증명하는 액세스 토큰을 보냅니다.

흐름은 다음과 같습니다:

  1. Azure AD (Entra ID)에 애플리케이션 등록
  2. 클라이언트 ID 및 클라이언트 비밀 얻기
  3. Azure의 토큰 엔드포인트에서 액세스 토큰 요청
  4. API 호출에 해당 토큰 포함

1단계: 애플리케이션 등록

Azure Portal → Microsoft Entra ID → 앱 등록 → 새 등록으로 이동합니다.

이름을 지정하고, 내부 앱의 경우 "이 조직 디렉터리의 계정만"을 선택한 다음 등록합니다. 다음을 얻게 됩니다:

2단계: 클라이언트 비밀 생성

앱 등록에서 '인증서 및 비밀' → '새 클라이언트 비밀'로 이동합니다. 비밀 값을 즉시 복사하십시오. 다시 볼 수 없습니다.

3단계: 권한 할당

'API 권한' → '권한 추가'로 이동합니다. Azure Storage의 경우 "Azure Storage" → "user_impersonation"을 선택합니다. Azure Management API의 경우 "Azure Service Management" → "user_impersonation"을 선택합니다.

4단계: 액세스 토큰 가져오기

curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=https://storage.azure.com/.default" \
  -d "grant_type=client_credentials"

응답:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
  "expires_in": 3599,
  "token_type": "Bearer"
}

5단계: 토큰 사용

curl -X GET "https://youraccount.blob.core.windows.net/container?restype=container&comp=list" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "x-ms-version: 2023-01-03"

원시 HTTP 대신 Azure SDK 사용

프로덕션 코드에는 Azure SDK를 사용하십시오. 토큰 새로 고침, 재시도, 직렬화를 처리합니다.

import { DefaultAzureCredential } from '@azure/identity'
import { BlobServiceClient } from '@azure/storage-blob'

// Automatically uses your Azure CLI login or environment variables
const credential = new DefaultAzureCredential()
const blobServiceClient = new BlobServiceClient(
  'https://youraccount.blob.core.windows.net',
  credential
)

// List containers
for await (const container of blobServiceClient.listContainers()) {
  console.log(container.name)
}

하지만 테스트, 디버깅, 문서화를 위해서는 원시 HTTP 호출을 이해해야 합니다. 바로 이 지점에서 Apidog가 유용합니다.

Azure Storage API

Azure Storage는 가장 일반적으로 사용되는 Azure 서비스입니다. 다음을 포함합니다:

Blob Storage API

컨테이너 나열:

GET https://{account}.blob.core.windows.net/?comp=list
Authorization: Bearer {token}
x-ms-version: 2023-01-03

컨테이너 생성:

PUT https://{account}.blob.core.windows.net/{container}?restype=container
Authorization: Bearer {token}
x-ms-version: 2023-01-03

Blob 업로드:

PUT https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Content-Type: text/plain

Hello, Azure Blob Storage!

Blob 다운로드:

GET https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03

Apidog로 테스트하기

Azure Storage API는 특정 헤더(x-ms-version, 올바른 인증 형식)를 필요로 합니다. Apidog는 다음을 돕습니다:

  1. 이를 재사용 가능한 요청으로 저장
  2. 계정 이름 및 토큰에 환경 변수 사용
  3. 응답이 예상 스키마와 일치하는지 검증

Apidog로 Azure Storage API 설계 및 테스트

Azure Compute API

Azure Compute를 사용하면 가상 머신, 컨테이너 및 서버리스 함수를 관리할 수 있습니다.

Azure Functions API

Azure Functions는 관리 작업을 위한 REST API를 가지고 있습니다.

함수 앱의 함수 나열:

GET https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions?api-version=2023-01-01
Authorization: Bearer {management-token}

함수 트리거 (HTTP 트리거):

POST https://{app-name}.azurewebsites.net/api/{function-name}
Content-Type: application/json

{
  "name": "Azure",
  "message": "Hello from API"
}

함수 키 가져오기:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions/{function-name}/listKeys?api-version=2023-01-01
Authorization: Bearer {management-token}

가상 머신 API

VM 나열:

GET https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01
Authorization: Bearer {management-token}

VM 시작:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2023-07-01
Authorization: Bearer {management-token}

VM 중지:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/powerOff?api-version=2023-07-01
Authorization: Bearer {management-token}

Azure AI 서비스 API

Azure는 OpenAI 모델을 호스팅하고 비전, 음성 및 언어 인지 서비스를 제공합니다.

Azure OpenAI API

완료 가져오기:

POST https://{resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version=2024-02-15-preview
api-key: {your-api-key}
Content-Type: application/json

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Azure?"}
  ],
  "max_tokens": 500
}

배포 나열:

GET https://{resource-name}.openai.azure.com/openai/deployments?api-version=2024-02-15-preview
api-key: {your-api-key}

Cognitive Services API

텍스트 분석 - 감성 분석:

POST https://{resource-name}.cognitiveservices.azure.com/text/analytics/v3.1/sentiment
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/json

{
  "documents": [
    {
      "id": "1",
      "language": "en",
      "text": "I love Azure APIs. They work great!"
    }
  ]
}

컴퓨터 비전 - 이미지 분석:

POST https://{resource-name}.cognitiveservices.azure.com/vision/v3.2/analyze?visualFeatures=Description,Tags
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/octet-stream

[binary image data]

Apidog로 Azure API 테스트하기

Azure API는 복잡한 인증과 정교한 헤더를 요구합니다. curl로 수동으로 테스트하는 것은 빠르게 오류에 취약해집니다. Apidog는 다음을 통해 이를 해결합니다:

1. 환경 관리

Azure API는 여러 엔드포인트를 사용합니다:

각각에 대해 Apidog에서 환경을 생성합니다:

# Development
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: devstorage
OPENAI_RESOURCE: dev-openai

# Production
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: prodstorage
OPENAI_RESOURCE: prod-openai

2. 토큰 새로고침을 위한 사전 요청 스크립트

Azure 토큰은 1시간 후에 만료됩니다. 사전 요청 스크립트를 추가하세요:

// Check if token is expired
const tokenExpiry = pm.environment.get('token_expiry')
const now = Date.now() / 1000

if (!tokenExpiry || now >= tokenExpiry) {
  // Request new token
  const response = await pm.sendRequest({
    url: 'https://login.microsoftonline.com/' + pm.environment.get('tenant_id') + '/oauth2/v2.0/token',
    method: 'POST',
    header: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_id', value: pm.environment.get('client_id') },
        { key: 'client_secret', value: pm.environment.get('client_secret') },
        { key: 'scope', value: 'https://management.azure.com/.default' },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  })
  
  const data = response.json()
  pm.environment.set('management_token', data.access_token)
  pm.environment.set('token_expiry', now + data.expires_in)
}

3. 응답 유효성 검사

Azure 응답이 예상 스키마와 일치하는지 검증합니다:

// Test that blob list returns expected structure
pm.test('Response has containers', () => {
  const xml = pm.response.text()
  pm.expect(xml).to.include('<Containers>')
  pm.expect(xml).to.include('<Container>')
})

pm.test('Response is valid XML', () => {
  pm.response.to.be.ok
  pm.response.to.have.header('Content-Type', 'application/xml')
})

Apidog로 Azure API 테스트 시작하기 - 무료

일반적인 오류 및 해결 방법

401 Unauthorized (인증되지 않음)

원인: 유효하지 않거나 만료된 토큰.

해결:

  1. 토큰이 만료되지 않았는지 확인 (expires_in은 일반적으로 3600초)
  2. 호출하는 API와 범위가 일치하는지 확인
  3. 앱 등록에 올바른 권한이 있는지 확인

403 Forbidden (금지됨)

원인: 토큰은 유효하지만 권한이 부족합니다.

해결:

  1. Azure Portal에서 리소스로 이동
  2. 액세스 제어 (IAM) 확인
  3. 앱의 서비스 주체에 대한 역할 할당 추가

404 Not Found (찾을 수 없음)

원인: 잘못된 엔드포인트 또는 리소스가 존재하지 않음.

해결:

  1. URL의 리소스 이름 확인
  2. 쿼리 문자열의 API 버전 확인
  3. 올바른 리소스 그룹에 리소스가 있는지 확인

429 Too Many Requests (요청이 너무 많음)

원인: Azure의 속도 제한에 도달했습니다.

해결:

  1. 지수 백오프 구현
  2. x-ms-ratelimit-remaining 헤더 확인
  3. 요청 일괄 처리 고려
async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.statusCode === 429) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
      } else {
        throw error
      }
    }
  }
}

대안 및 비교

기능 Azure API AWS API GCP API
인증 Azure AD (OAuth 2.0) IAM (Sig v4) OAuth 2.0
SDK 품질 우수함 우수함 우수함
문서 포괄적이지만 산재함 서비스별 서비스별
속도 제한 구독별 서비스별 프로젝트별
무료 등급 12개월 + 항상 무료 12개월 항상 무료 + 크레딧

Azure의 인증은 AWS의 서명 기반 접근 방식보다 복잡하지만, 엔터프라이즈 ID 시스템과 더 잘 통합됩니다.

실제 사용 사례

전자상거래 플랫폼. Shopify의 대안이 되는 플랫폼은 제품 이미지에 Azure Blob Storage를, 주문 처리 웹훅에 Azure Functions를, 제품 설명에 Azure OpenAI를 사용합니다. 이들은 변경 사항을 배포하기 전에 Apidog에서 모든 API 호출을 테스트합니다.

헬스케어 SaaS. 의료 기록 시스템은 환자 데이터에 Azure Cosmos DB를, HL7 메시지 처리에 Azure Functions를, 비밀 관리에 Azure Key Vault를 사용합니다. API 테스트는 모든 응답 스키마를 검증하여 HIPAA 규정 준수를 보장합니다.

AI 스타트업. AI 에이전트를 구축하는 회사는 LLM 호출에 Azure OpenAI를, 훈련 데이터에 Azure Storage를, 배포에 Azure Container Apps를 사용합니다. 이들은 로컬 개발 중에 Apidog를 사용하여 Azure API를 모의(mock)합니다.

마무리

배운 내용은 다음과 같습니다:

다음 단계:

  1. Azure AD에 앱을 등록하고 자격 증명 얻기
  2. 클라이언트 자격 증명 흐름을 사용하여 액세스 토큰 요청
  3. 첫 번째 Azure Storage API 호출 수행
  4. 해당 호출을 Apidog에 재사용 가능한 요청으로 저장
  5. 프로젝트의 Azure API를 위한 컬렉션 구축

Apidog로 Azure API 테스트 - 무료

자주 묻는 질문 (FAQ)

Azure AD와 Microsoft Entra ID의 차이점은 무엇인가요? 동일한 것입니다. Microsoft는 2023년에 Azure Active Directory를 Microsoft Entra ID로 리브랜딩했습니다. 문서에서 두 가지 이름을 모두 볼 수 있을 것입니다. 새 문서를 작성할 때는 Entra ID를 사용하지만, 이전 문서나 코드에서는 Azure AD가 여전히 일반적이라는 점을 알아두세요.

Azure OpenAI용 API 키는 어떻게 얻나요? Azure Portal → Azure OpenAI → 리소스 → 키 및 엔드포인트로 이동합니다. 두 개의 키를 볼 수 있으며, 둘 중 하나를 사용해도 됩니다. 보안을 위해 주기적으로 재생성하십시오. OpenAI의 공개 API와 달리, Azure OpenAI는 먼저 Azure 구독 및 리소스 배포를 필요로 합니다.

management.azure.com과 서비스별 엔드포인트의 차이점은 무엇인가요?management.azure.com은 Azure Resource Manager 엔드포인트입니다. 이는 Azure 리소스 자체에 대한 CRUD 작업(VM 생성, 스토리지 계정 삭제)을 위한 것입니다. 서비스별 엔드포인트({account}.blob.core.windows.net, {resource}.openai.azure.com)는 해당 리소스를 사용하는 것(파일 업로드, 텍스트 생성)을 위한 것입니다. 각기 다른 토큰이 필요합니다.

Azure 액세스 토큰은 얼마나 오래 지속되나요? 일반적으로 1시간(3600초)입니다. 이전 토큰이 만료되기 전에 새 토큰을 요청할 수 있습니다. 토큰 응답의 expires_in 필드를 사용하여 언제 새로 고쳐야 하는지 알 수 있습니다. 모든 API 호출에서 새 토큰을 요청하지 마십시오. 이는 비효율적입니다.

클라이언트 비밀 대신 관리 ID를 사용할 수 있나요? 예, Azure에서 실행되는 프로덕션 워크로드에는 그렇게 해야 합니다. 관리 ID는 클라이언트 비밀을 저장할 필요성을 없애줍니다. 이들은 Azure VM, Functions, Container Apps, AKS와 함께 작동합니다. 로컬 개발의 경우 Azure CLI (az login) 또는 클라이언트 비밀이 포함된 환경 변수를 사용하세요.

Postman에서는 API 호출이 작동하는데 코드에서는 실패하는 이유는 무엇인가요? 헤더를 확인하십시오. Azure API는 헤더 이름에 대해 대소문자를 구분합니다. Postman이気づ지 못하는 헤더를 추가했을 수도 있습니다. Fiddler나 Apidog의 요청 검사와 같은 도구를 사용하여 Postman의 원시 요청과 코드를 비교하십시오.

Azure 구독 없이 로컬에서 Azure API를 테스트하려면 어떻게 해야 하나요? 구독 없이는 완전히 테스트할 수 없지만, Azure의 로컬 에뮬레이터를 사용할 수 있습니다:

Azure API 오류를 처리하는 가장 좋은 방법은 무엇인가요? Azure는 상세한 오류 JSON을 반환합니다. error.code 및 error.message 필드를 파싱하세요. 일반적인 코드는 다음과 같습니다:

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드