کلیدهای API

متابیس می‌تواند کلیدهای API ایجاد کند تا درخواست‌های برنامه‌نویسی به API را احراز هویت کند. برای تنظیم مجوزها برای یک کلید API، می‌توانید کلید را به یک گروه اختصاص دهید.

هشدار منصفانه دربارهٔ API متابیس

ما API متابیس را version نمی‌کنیم. به ندرت endpointهای API را تغییر می‌دهیم، و تقریباً هرگز آن‌ها را حذف نمی‌کنیم، اما اگر کدی بنویسید که به API وابسته است، احتمال دارد که در آینده نیاز به به‌روزرسانی کد خود داشته باشید.

با این حال، زمان‌هایی وجود دارد که کار با API خوب است، مثل هنگام مدیریت مجوزها با تعداد زیادی افراد و گروه، یا آرشیو دسته‌ای، یا ایجاد محتوا. بنابراین قابلیت ایجاد کلیدهای API برای احراز هویت درخواست‌های برنامه‌نویسی شما را اضافه کردیم.

ایجاد یک کلید API

برای ایجاد یک کلید API:

1. روی آیکون gear در گوشهٔ بالا سمت راست کلیک کنید.
2. Admin settings را انتخاب کنید.
3. به تب Settings بروید.
4. روی تب Authentication در منوی چپ کلیک کنید.
5. به API Keys اسکرول کنید و روی Manage کلیک کنید.
6. روی دکمهٔ Create API Key کلیک کنید.
7. یک نام کلید وارد کنید. می‌توانید چندین کلید API داشته باشید، بنابراین نامی بدهید که به شما کمک کند به خاطر بیاورید از کلید برای چه استفاده می‌کنید.
8. یک گروه انتخاب کنید. کلید همان مجوزهای اعطا شده به آن گروه را خواهد داشت.
9. روی Create کلیک کنید.
10. کلید API تولید شده را کپی کنید و در جایی امن ذخیره کنید. متابیس نمی‌تواند کلید را دوباره به شما نشان دهد. اگر کلید را گم کنید، باید یک کلید جدید تولید کنید.

ایجاد کلیدهای API از فایل config

اگر در یک پلن self-hosted Pro یا Enterprise هستید، می‌توانید کلیدهای API را از طریق فایل پیکربندی ایجاد کنید.

مدیریت کلیدهای API

برای مشاهده و مدیریت کلیدهای API موجود:

1. روی آیکون gear در گوشهٔ بالا سمت راست کلیک کنید.
2. Admin settings را انتخاب کنید.
3. به تب Settings بروید.
4. روی تب Authentication در منوی چپ کلیک کنید.
5. به API Keys اسکرول کنید و روی Manage کلیک کنید.

ویرایش کلیدهای API

برای ویرایش یک کلید API، به کلیدی که می‌خواهید ویرایش کنید اسکرول کنید و روی آیکون pencil کلیک کنید. متابیس یک مودال Edit API Key باز می‌کند که می‌توانید در آن ویرایش کنید:

• نام کلید
• کدام گروه کلید به آن تعلق دارد.
• تغییر (تولید مجدد) کلید. متابیس کلید API موجود را با یک کلید جدید جایگزین می‌کند. نمی‌توانید کلید قدیمی را بازیابی کنید.

حذف کلیدهای API

نمی‌توانید یک کلید API حذف‌شده را بازیابی کنید. باید یک کلید جدید ایجاد کنید.

برای حذف یک کلید API:

1. روی آیکون gear در گوشهٔ بالا سمت راست کلیک کنید.
2. Admin settings را انتخاب کنید.
3. به تب Settings بروید.
4. روی تب Authentication در منوی چپ کلیک کنید.
5. به API Keys اسکرول کنید و روی Manage کلیک کنید.
6. کلیدی که می‌خواهید حذف کنید را انتخاب کنید و روی آیکون trash کلیک کنید.
7. متابیس یک مودال Delete API Key باز می‌کند. روی دکمهٔ Delete API Key کلیک کنید.

متابیس کلیدهای API مرتبط با گروهی که حذف می‌شود را به گروه All users منتقل می‌کند

اگر کلیدهای API اختصاص داده شده به یک گروه دارید، اما سپس کسی آن گروه را حذف می‌کند، کلیدهای API همچنان کار می‌کنند، اما متابیس آن کلیدها را به گروه All users دوباره اختصاص می‌دهد. اگر می‌خواهید گروه آن‌ها را تغییر دهید، باید کلیدها را به صورت دستی ویرایش کنید.

مثال درخواست‌های GET

در اینجا برخی مثال‌های درخواست GET آورده شده است که گروه‌ها را در متابیس شما برمی‌گرداند. این مثال‌ها فرض می‌کنند که متابیس را به صورت محلی روی پورت پیش‌فرض اجرا می‌کنید: 3000.

مثال curl

YOUR_API_KEY را با کلید API که در بالا تولید کردید جایگزین کنید.

curl \
-H 'x-api-key: YOUR_API_KEY' \
-X GET 'http://localhost:3000/api/permissions/group'

مثال JavaScript

فرض کنید کلید خود را به‌عنوان یک متغیر محیطی مثل این تنظیم کرده‌اید:

export METABASE_API_KEY="YOUR_API_KEY"

در اینجا یک درخواست GET پایه با استفاده از fetch برای دریافت لیست گروه‌ها آورده شده است. می‌توانید کد را کپی کنید، به‌عنوان فایل ذخیره کنید (مثلاً به‌عنوان api-test.js)، و کد را با node api-test.js اجرا کنید.

// فرض کنید کلید را در process با
// `export METABASE_API_KEY="YOUR_KEY_HERE"` تنظیم کرده‌اید
const API_KEY = process.env.METABASE_API_KEY;

const init = {
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
  },
};

const host = "http://127.0.0.1:3000";

async function getGroups() {
  const response = await fetch(`${host}/api/permissions/group`, init);
  return response.json();
}

getGroups().then((groups) => console.log("Groups in your Metabase:", groups));

مطالعهٔ بیشتر

• مرجع API متابیس.
• کار با API متابیس.