วิธีใช้ Azure APIs

สรุปเนื้อหาสำคัญ (TL;DR)

Azure APIs ช่วยให้คุณเข้าถึงบริการคลาวด์ของ Microsoft โดยใช้โปรแกรมได้ ไม่ว่าจะเป็นพื้นที่เก็บข้อมูล (storage), การประมวลผล (compute), ฐานข้อมูล (databases), AI และอื่น ๆ คุณใช้ Azure Active Directory (Entra ID) เพื่อยืนยันตัวตน ได้รับ access token และเรียกใช้ REST endpoints สำหรับการทดสอบและจัดทำเอกสาร ให้ใช้ Apidog เพื่อบันทึกการเรียกใช้ API ของคุณ ตรวจสอบความถูกต้องของการตอบกลับเทียบกับ schemas และแชร์คอลเลกชันกับทีมของคุณ

บทนำ

Microsoft Azure มีบริการมากกว่า 200 รายการ แต่ละบริการมี API เป็นของตัวเอง นักพัฒนาส่วนใหญ่จะต้องใช้งานอย่างน้อยสองสามรายการ เช่น Azure Blob Storage สำหรับไฟล์, Azure Functions สำหรับ serverless หรือ Azure OpenAI สำหรับ LLMs

แต่ปัญหาคืออะไร? เอกสารของ Azure มีขนาดใหญ่และกระจัดกระจาย คุณอาจใช้เวลาหลายชั่วโมงในการค้นหา endpoint ที่ถูกต้อง ทำความเข้าใจการยืนยันตัวตน และแก้ไขข้อผิดพลาดว่าทำไมคำขอของคุณจึงส่งคืน 401 Unauthorized

คู่มือนี้มุ่งเน้นไปที่ API ที่คุณใช้งานจริง ไม่ใช่บริการ 200 รายการ แต่เป็น 5-10 รายการที่ขับเคลื่อนแอปพลิเคชันส่วนใหญ่ คุณจะได้เรียนรู้รูปแบบการยืนยันตัวตน ข้อผิดพลาดทั่วไป และวิธีทดสอบการผสานรวม Azure ของคุณก่อนที่จะปรับใช้

💡

หากคุณกำลังสร้างระบบโดยใช้ Azure APIs, Apidog จะช่วยคุณออกแบบ ทดสอบ และจัดทำเอกสารการผสานรวมเหล่านั้น คุณสามารถบันทึกการเรียกใช้ Azure API ของคุณเป็นคอลเลกชัน เพิ่มตัวแปรสภาพแวดล้อมสำหรับการสมัครสมาชิกที่แตกต่างกัน และตรวจสอบว่าการตอบสนองตรงกับ schemas ที่คาดไว้ ซึ่งจะช่วยตรวจจับข้อผิดพลาดในการกำหนดค่าก่อนที่จะส่งผลกระทบต่อการผลิต

ปุ่ม

ทดสอบ Azure APIs ของคุณด้วย Apidog - ฟรี

เมื่อจบคู่มือนี้ คุณจะสามารถ:

ตั้งค่าการยืนยันตัวตนของ Azure ได้อย่างถูกต้อง (เป็นแหล่งที่มาของข้อผิดพลาดอันดับ 1)
เรียกใช้ Azure Storage, Compute และ AI APIs พร้อมตัวอย่างการทำงาน
แก้ไขข้อผิดพลาดทั่วไปของ Azure API
ทดสอบและจัดทำเอกสารการผสานรวม Azure ของคุณด้วย Apidog

ปัญหาการยืนยันตัวตน (และวิธีแก้ไข)

การเรียกใช้ Azure API ทุกครั้งต้องมีการยืนยันตัวตน หากทำผิดพลาด ทุกอย่างจะล้มเหลว นี่คือจุดที่นักพัฒนาส่วนใหญ่ติดขัด

Azure Active Directory / Microsoft Entra ID

Azure ใช้ OAuth 2.0 สำหรับการยืนยันตัวตน API คุณไม่ได้ส่งชื่อผู้ใช้และรหัสผ่าน แต่คุณส่ง access token ที่พิสูจน์ว่าคุณคือใครและคุณสามารถทำอะไรได้บ้าง

ขั้นตอนมีดังนี้:

ลงทะเบียนแอปพลิเคชันใน Azure AD (Entra ID)
รับ client ID และ client secret
ขอ access token จาก endpoint โทเค็นของ Azure
รวมโทเค็นนั้นในการเรียกใช้ API ของคุณ

ขั้นตอนที่ 1: ลงทะเบียนแอปพลิเคชัน

ไปที่ Azure Portal → Microsoft Entra ID → App registrations → New registration

ตั้งชื่อ เลือก “Accounts in this organizational directory only” สำหรับแอปภายใน และลงทะเบียน คุณจะได้รับ:

Application (client) ID: 12345678-1234-1234-1234-123456789abc
Directory (tenant) ID: 87654321-4321-4321-4321-cba987654321

ขั้นตอนที่ 2: สร้าง client secret

ในการลงทะเบียนแอปของคุณ ไปที่ Certificates & secrets → New client secret คัดลอกค่า secret ทันที คุณจะไม่เห็นมันอีก

Client secret: abc123~DEF456-ghi789

ขั้นตอนที่ 3: กำหนดสิทธิ์

ไปที่ API permissions → Add a permission สำหรับ Azure Storage ให้เลือก “Azure Storage” → “user_impersonation” สำหรับ Azure Management APIs ให้เลือก “Azure Service Management” → “user_impersonation”

ขั้นตอนที่ 4: รับ access token

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"

การใช้ Azure SDK แทน HTTP ดิบ

สำหรับโค้ดที่ใช้งานจริง ให้ใช้ Azure SDK จะจัดการการรีเฟรชโทเค็น, การลองใหม่ และการทำให้เป็นอนุกรม (serialization)

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 APIs

Azure Storage เป็นบริการ Azure ที่ใช้บ่อยที่สุด ประกอบด้วย:

Blob Storage: ไฟล์, รูปภาพ, การสำรองข้อมูล
Queue Storage: คิวข้อความ
Table Storage: ที่เก็บคีย์-ค่าแบบ NoSQL
File Storage: การแชร์ไฟล์ SMB

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 APIs ต้องการ headers เฉพาะ (x-ms-version, รูปแบบการยืนยันตัวตนที่ถูกต้อง) Apidog ช่วยคุณได้:

บันทึกสิ่งเหล่านี้เป็นคำขอที่นำกลับมาใช้ใหม่ได้
ใช้ตัวแปรสภาพแวดล้อมสำหรับชื่อบัญชีและโทเค็น
ตรวจสอบการตอบสนองที่ตรงกับ schemas ที่คาดไว้

ออกแบบและทดสอบ Azure Storage APIs ด้วย Apidog

Azure Compute APIs

Azure Compute ให้คุณจัดการเครื่องเสมือน (virtual machines), คอนเทนเนอร์ และฟังก์ชันไร้เซิร์ฟเวอร์

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 trigger):

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}

Virtual Machines 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 Services APIs

Azure เป็นโฮสต์ของโมเดล OpenAI และให้บริการด้าน cognitive services สำหรับการมองเห็น การพูด และภาษา

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

Text Analytics - ความรู้สึก:

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!"
    }
  ]
}

Computer Vision - วิเคราะห์รูปภาพ:

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]

การทดสอบ Azure APIs ด้วย Apidog

Azure APIs มีการยืนยันตัวตนที่ซับซ้อนและต้องใช้ headers ที่แม่นยำ การทดสอบด้วยตนเองโดยใช้ curl มักเกิดข้อผิดพลาดได้ง่าย Apidog แก้ปัญหานี้โดย:

1. การจัดการสภาพแวดล้อม

Azure APIs มี endpoints หลายรายการ:

management.azure.com สำหรับ control plane
{account}.blob.core.windows.net สำหรับ storage
{resource}.openai.azure.com สำหรับ AI

สร้างสภาพแวดล้อมใน 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 ตรงกับ schemas ที่คาดไว้:

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

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

เริ่มทดสอบ Azure APIs ด้วย Apidog - ฟรี

ข้อผิดพลาดทั่วไปและวิธีแก้ไข

401 Unauthorized

สาเหตุ: โทเค็นไม่ถูกต้องหรือหมดอายุ

วิธีแก้ไข:

ตรวจสอบว่าโทเค็นยังไม่หมดอายุ (expires_in มักจะเป็น 3600 วินาที)
ตรวจสอบว่า scope ตรงกับ API ที่คุณกำลังเรียกใช้
ตรวจสอบให้แน่ใจว่าการลงทะเบียนแอปมีสิทธิ์ที่ถูกต้อง

403 Forbidden

สาเหตุ: โทเค็นถูกต้อง แต่ไม่มีสิทธิ์

วิธีแก้ไข:

ไปที่ทรัพยากรใน Azure Portal
ตรวจสอบ Access control (IAM)
เพิ่มการกำหนดบทบาทสำหรับ service principal ของแอปคุณ

404 Not Found

สาเหตุ: Endpoint ผิดพลาด หรือทรัพยากรไม่มีอยู่

วิธีแก้ไข:

ตรวจสอบชื่อทรัพยากรใน URL
ตรวจสอบเวอร์ชัน API ใน query string
ตรวจสอบให้แน่ใจว่าทรัพยากรมีอยู่ใน resource group ที่ถูกต้อง

429 Too Many Requests

สาเหตุ: คุณใช้งานเกินขีดจำกัดอัตรา (rate limits) ของ Azure

วิธีแก้ไข:

ใช้ exponential backoff
ตรวจสอบ header x-ms-ratelimit-remaining
พิจารณาการรวมคำขอเป็นกลุ่ม

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 APIs	AWS APIs	GCP APIs
การยืนยันตัวตน	Azure AD (OAuth 2.0)	IAM (Sig v4)	OAuth 2.0
คุณภาพ SDK	ยอดเยี่ยม	ยอดเยี่ยม	ยอดเยี่ยม
เอกสารประกอบ	ครอบคลุมแต่กระจัดกระจาย	เฉพาะบริการ	เฉพาะบริการ
การจำกัดอัตรา	ต่อการสมัครสมาชิก	ต่อบริการ	ต่อโปรเจกต์
ระดับฟรี	12 เดือน + ฟรีตลอดไป	12 เดือน	ฟรีตลอดไป + เครดิต

การยืนยันตัวตนของ Azure ซับซ้อนกว่าวิธีการที่ใช้ลายเซ็นของ AWS แต่ผสานรวมเข้ากับระบบยืนยันตัวตนขององค์กรได้ดีกว่า

กรณีการใช้งานจริง

แพลตฟอร์มอีคอมเมิร์ซ แพลตฟอร์มทางเลือกของ Shopify ใช้ Azure Blob Storage สำหรับรูปภาพสินค้า, Azure Functions สำหรับ webhooks การประมวลผลคำสั่งซื้อ และ Azure OpenAI สำหรับคำอธิบายสินค้า พวกเขาทดสอบการเรียกใช้ API ทั้งหมดใน Apidog ก่อนปรับใช้การเปลี่ยนแปลง

Healthcare SaaS ระบบบันทึกทางการแพทย์ใช้ Azure Cosmos DB สำหรับข้อมูลผู้ป่วย, Azure Functions สำหรับการประมวลผลข้อความ HL7 และ Azure Key Vault สำหรับ secrets การทดสอบ API ช่วยให้มั่นใจได้ถึงการปฏิบัติตามข้อกำหนด HIPAA โดยการตรวจสอบ schemas การตอบสนองทุกครั้ง

AI startup บริษัทที่สร้าง AI agents ใช้ Azure OpenAI สำหรับการเรียกใช้ LLM, Azure Storage สำหรับข้อมูลการฝึกอบรม และ Azure Container Apps สำหรับการปรับใช้ พวกเขาใช้ Apidog เพื่อ mock Azure APIs ในระหว่างการพัฒนาในเครื่อง

สรุป

สิ่งที่คุณได้เรียนรู้:

การยืนยันตัวตนของ Azure ใช้โทเค็น OAuth 2.0 จาก Azure AD (Entra ID)
Storage APIs ต้องใช้ header x-ms-version และ Bearer tokens ที่ถูกต้อง
Compute APIs ใช้ Azure Resource Manager endpoint
AI services ใช้ API keys หรือ AAD tokens ขึ้นอยู่กับบริการ
ทดสอบและจัดทำเอกสารการผสานรวม Azure ของคุณด้วย Apidog

ขั้นตอนต่อไปของคุณ:

ลงทะเบียนแอปใน Azure AD และรับข้อมูลรับรองของคุณ
ขอ access token โดยใช้ client credentials flow
ทำการเรียกใช้ Azure Storage API ครั้งแรกของคุณ
บันทึกการเรียกใช้นั้นใน Apidog เป็นคำขอที่นำกลับมาใช้ใหม่ได้
สร้างคอลเลกชันสำหรับ Azure APIs ของโปรเจกต์ของคุณ

ทดสอบ Azure APIs ด้วย Apidog - ฟรี

คำถามที่พบบ่อย (FAQ)

ความแตกต่างระหว่าง Azure AD กับ Microsoft Entra ID คืออะไร?ทั้งสองคือสิ่งเดียวกัน Microsoft ได้เปลี่ยนชื่อ Azure Active Directory เป็น Microsoft Entra ID ในปี 2023 คุณจะเห็นทั้งสองชื่อในเอกสารประกอบ ใช้ Entra ID เมื่อสร้างเอกสารใหม่ แต่โปรดทราบว่า Azure AD ยังคงเป็นที่นิยมในบทความและโค้ดเก่าๆ

ฉันจะรับ API key สำหรับ Azure OpenAI ได้อย่างไร?ไปที่ Azure Portal → Azure OpenAI → ทรัพยากรของคุณ → Keys and Endpoint คุณจะเห็นสองคีย์ อันไหนก็ได้ใช้ได้หมด สร้างใหม่เป็นระยะเพื่อความปลอดภัย ต่างจาก OpenAI Public API ตรงที่ Azure OpenAI ต้องมีการสมัครสมาชิก Azure และการปรับใช้ทรัพยากรก่อน

ความแตกต่างระหว่าง management.azure.com กับ service-specific endpoints คืออะไร?management.azure.com คือ Azure Resource Manager endpoint ใช้สำหรับการดำเนินการ CRUD บนทรัพยากร Azure เอง (สร้าง VM, ลบ storage account) ส่วน service-specific endpoints ({account}.blob.core.windows.net, {resource}.openai.azure.com) ใช้สำหรับการใช้งานทรัพยากรเหล่านั้น (อัปโหลดไฟล์, สร้างข้อความ) คุณต้องใช้โทเค็นที่แตกต่างกันสำหรับแต่ละอย่าง

Azure access tokens มีอายุนานเท่าใด?โดยทั่วไปคือ 1 ชั่วโมง (3600 วินาที) คุณสามารถขอโทเค็นใหม่ก่อนที่โทเค็นเก่าจะหมดอายุ ใช้ฟิลด์ expires_in จากการตอบสนองโทเค็นเพื่อทราบว่าเมื่อใดควรรีเฟรช อย่าขอโทเค็นใหม่ทุกครั้งที่เรียกใช้ API เพราะไม่มีประสิทธิภาพ

ฉันสามารถใช้ managed identities แทน client secrets ได้หรือไม่?ได้ และคุณควรใช้สำหรับปริมาณงานการผลิตที่ทำงานใน Azure Managed identities ช่วยขจัดความจำเป็นในการจัดเก็บ client secrets ทำงานร่วมกับ Azure VMs, Functions, Container Apps และ AKS ได้ สำหรับการพัฒนาในเครื่อง ให้ใช้ Azure CLI (az login) หรือตัวแปรสภาพแวดล้อมพร้อม client secrets

ทำไมการเรียกใช้ API ของฉันถึงทำงานใน Postman แต่ล้มเหลวในโค้ด?ตรวจสอบ headers Azure APIs เป็นแบบ case-sensitive สำหรับชื่อ header Postman อาจเพิ่ม headers ที่คุณไม่ทันสังเกต เปรียบเทียบคำขอ raw จาก Postman กับโค้ดของคุณโดยใช้เครื่องมือเช่น Fiddler หรือการตรวจสอบคำขอของ Apidog

ฉันจะทดสอบ Azure APIs ในเครื่องโดยไม่มีการสมัครสมาชิก Azure ได้อย่างไร?คุณไม่สามารถทดสอบได้อย่างสมบูรณ์หากไม่มีการสมัครสมาชิก แต่คุณสามารถใช้ emulators ในเครื่องของ Azure ได้:

Azurite สำหรับ Azure Storage
Azure Functions Core Tools สำหรับ Functions
ใช้ Apidog เพื่อ mock การตอบสนองของ Azure API

วิธีที่ดีที่สุดในการจัดการข้อผิดพลาดของ Azure API คืออะไร?Azure จะส่งคืน JSON ข้อผิดพลาดที่มีรายละเอียด วิเคราะห์ฟิลด์ error.code และ error.message รหัสทั่วไป:

AuthenticationFailed - ตรวจสอบโทเค็นของคุณ
ResourceNotFound - ตรวจสอบชื่อทรัพยากร
OperationNotAllowed - ตรวจสอบขีดจำกัดการสมัครสมาชิกของคุณ