JSON-2 در Odoo 19؛ اتصال امن و اولین درخواست فقط‌خواندنی

برای اتصال به API در Odoo 19، با یک درخواست فقط‌خواندنی به JSON-2 شروع کنید: نشانی درست، کاربر اختصاصی، کلید معتبر و دامنهٔ دادهٔ محدود را مشخص کنید؛ سپس پاسخ را با همان دسترسی در رابط کاربری مقایسه کنید. دریافت پاسخ موفق، تنها بخشی از پذیرش اتصال است؛ باید بدانید چه اطلاعاتی قابل مشاهده بوده و چه کسی مسئول نگهداری کلید است.

این راهنما برای توسعه‌دهنده و مدیر سامانه‌ای است که می‌خواهد نخستین اتصال سازمانی را قابل بررسی تحویل دهد. مثال‌ها آموزشی‌اند و روی سامانهٔ عملیاتی مشتری اجرا نشده‌اند. ابتدا در محیط آزمایش با دادهٔ غیرحساس کار کنید. دامنه و نام دیتابیس نمونه‌اند؛ هیچ نشانی داخلی، کلید یا رکورد واقعی در مثال وجود ندارد.

JSON-2 در Odoo 19 چه چیزی را تغییر می‌دهد؟

JSON-2 از نسخهٔ ۱۹ معرفی شده است. درخواست به مسیر /json/2/<model>/<method> فرستاده می‌شود و بدنه، یک شیء JSON از پارامترهای متد است. در اتصال ماشینی، کلید API در سربرگ Authorization: bearer … قرار می‌گیرد. مشخصات دقیق درخواست را در مستند رسمی JSON-2 بررسی کنید.

برای مهاجرت یک اتصال قدیمی، فهرستی از مدل‌ها، متدها، پارامترها و خروجی‌های مورد انتظار بسازید. عوض‌کردن نشانی درخواست بدون بازبینی قرارداد داده کافی نیست. در مستندات فعلی، حذف سرویس‌های قدیمی XML-RPC و JSON-RPC برای Odoo 22 و نسخهٔ Online 21.1 برنامه‌ریزی شده است؛ این برنامه دربارهٔ همهٔ کنترلرهای سفارشی jsonrpc نیست. برای زمان‌بندی مهاجرت، صفحهٔ رسمی RPC را دوباره بررسی کنید؛ راهنماهای قدیمی ممکن است موعد متفاوتی نوشته باشند.

شرایط دسترسی API را با نوع میزبانی و قرارداد خود تطبیق دهید؛ مستند رسمی برای طرح‌های تجاری Odoo محدودیت طرح را ذکر می‌کند. این موضوع را با سالم‌بودن یک مسیر در نصب اختصاصی یکسان نگیرید. پیش از برآورد پروژه، قابلیت واقعی همان محیط و نسخهٔ نصب‌شده را تأیید کنید.

پیش از گرفتن کلید، قرارداد اتصال را بنویسید

یک برگهٔ کوتاه آماده کنید: سامانهٔ مبدأ، مالک فنی، محیط مقصد، مدل موردنیاز، فیلدهای مجاز، تناوب خواندن و معیار توقف. مثلاً «خواندن نام شرکت‌های طرف حساب در محیط آزمایش برای بررسی نگاشت شناسه‌ها» هدف روشن‌تری از «دسترسی به مخاطبان» است. این تعریف، انتخاب دسترسی و بررسی خروجی را ساده می‌کند.

حساب اتصال را از حساب روزمرهٔ مدیر جدا کنید. کلید، مجوزهای کاربر را جایگزین نمی‌کند؛ کنترل دسترسی مدل، قوانین رکورد و محدودیت فیلدها همچنان اهمیت دارند. برای توضیح لایه‌های دسترسی، مرجع امنیت Odoo را ببینید. پیشنهاد اجرایی ما این است که آزمون پذیرش دو بخش داشته باشد: دادهٔ مجاز دیده شود و داده‌ای که طبق سیاست سازمان خارج از محدوده است دیده نشود.

در بخش امنیت حساب، کلید را با نامی بیانگر کاربرد و تاریخ انقضا ایجاد کنید. مقدار آن را فقط در محل امن مصوب سازمان نگه دارید. این مقاله مدیریت خودکار کلید یا افزایش سطح دسترسی را آموزش نمی‌دهد. برای سرویس دائمی، تحویل راز به برنامه باید از سازوکار مدیریت اسرار همان محیط انجام شود؛ ورودی تعاملی نمونهٔ پایین صرفاً برای آزمون دستی است.

مسیر درخواست را پیش از داده بررسی کنید

ابتدا HTTPS معتبر را تأیید کنید. خاموش‌کردن بررسی گواهی برای عبور از خطا، معیار پذیرش نیست. راهنمای استقرار Odoo بر استفاده از HTTPS تأکید دارد. اگر نشانی به صفحهٔ ورود یا دامنه‌ای دیگر هدایت می‌شود، اول علت هدایت را با مسئول استقرار روشن کنید؛ کلید را همراه درخواست آزمایشی به مقصد نامعلوم نفرستید.

نام دیتابیس را از مسئول همان محیط بگیرید. در استقرار چنددیتابیسی، تنظیم مسیریابی و سربرگ X-Odoo-Database باید با هم سازگار باشند. نام شرکت، نام دیتابیس و نام میزبان الزاماً یکسان نیستند. حدس‌زدن این مقادیر، عیب‌یابی احراز هویت را با انتخاب محیط اشتباه مخلوط می‌کند.

اولین درخواست فقط‌خواندنی با Python

نمونهٔ زیر فقط از کتابخانهٔ استاندارد Python 3 استفاده می‌کند. نشانی و دیتابیس فرضی را با مشخصات محیط آزمایش جایگزین کنید. کلید با ورودی بدون نمایش دریافت می‌شود؛ آن را داخل فایل، آرگومان فرمان یا پیام پشتیبانی نگذارید. اجرای برنامه شمار رکوردها را چاپ می‌کند تا خروجی نمونه، دادهٔ مخاطبان را وارد ترمینال نکند.

import getpass
import json
import urllib.error
import urllib.request

BASE_URL = "https://mycompany.example.com"
DATABASE = "mycompany"

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

key = getpass.getpass("API key: ")
payload = {
    "domain": [["is_company", "=", True]],
    "fields": ["id", "name"],
    "limit": 5,
    "order": "id asc",
    "context": {"lang": "fa_IR"},
}
request = urllib.request.Request(
    BASE_URL + "/json/2/res.partner/search_read",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "bearer " + key,
        "X-Odoo-Database": DATABASE,
        "Content-Type": "application/json; charset=utf-8",
        "User-Agent": "json2-readonly-check/1.0",
    },
    method="POST",
)
try:
    opener = urllib.request.build_opener(NoRedirect())
    with opener.open(request, timeout=20) as response:
        rows = json.load(response)
    if not isinstance(rows, list):
        raise ValueError("Unexpected response format")
    print("Records received:", len(rows))
except urllib.error.HTTPError as error:
    print("HTTP status:", error.code)
except (urllib.error.URLError, TimeoutError):
    print("Connection or TLS check failed")
except ValueError:
    print("Response is not the expected JSON list")

متد search_read برای این آزمون، جست‌وجو و خواندن را در یک فراخوانی جمع می‌کند. limit اندازهٔ نمونه است، نه ابزار کنترل مجوز. محدودکردن فیلدها نیز جای قانون دسترسی را نمی‌گیرد. برای شناخت پارامترها و نوع فیلدهای نصب خود، از fields_get و مرجع ORM کمک بگیرید؛ نام فیلدهای سفارشی را از روی یک پایگاه دیگر کپی نکنید.

در JSON-2 یک شیء پارامتر ارسال می‌شود؛ پوشش قدیمی jsonrpc و آرایهٔ پارامترهای execute_kw را عیناً منتقل نکنید. همچنین همهٔ متدها فراخوانی یکسان ندارند؛ کنترلر، مدل، متد عمومی و امضای پارامترها را بررسی می‌کند. این رفتار در کد رسمی کنترلر نسخهٔ ۱۹ قابل مشاهده است. پیش از هر درخواست نوشتنی، قرارداد همان متد را جداگانه بررسی کنید.

وقتی پاسخ درست نیست، کدام شاهد را جمع کنیم؟

عیب‌یابی را با زمان اجرا، نشانی مسیر بدون راز، کد وضعیت و نوع خروجی شروع کنید. بدنهٔ کامل خطا ممکن است traceback یا جزئیات داخلی داشته باشد؛ آن را بی‌بررسی در تیکت عمومی قرار ندهید. نمونهٔ برنامه عمداً بدنهٔ خطا و سربرگ‌ها را چاپ نمی‌کند.

خروجی خالی به‌تنهایی خرابی نیست. با مسئول داده توافق کنید کدام رکورد آزمایشی باید قابل مشاهده باشد و مقایسه را با همان کاربر انجام دهید. پاسخ مدیر سامانه، مرجع مناسبی برای انتظار خروجی حساب محدود نیست. اگر دادهٔ اضافی دیده شد، اتصال را متوقف کنید و دامنهٔ دسترسی را پیش از توسعهٔ بعدی اصلاح کنید.

از نمونهٔ خواندن تا اتصال پایدار

هر فراخوانی JSON-2 تراکنش مستقل دارد. بنابراین چند درخواست متوالی، یک عملیات اتمی مشترک نمی‌سازند. در عملیات وابسته، مانند تغییر وضعیت همراه با ثبت یک نتیجه، طراحی متد واحد سمت سرور باید جدا بررسی شود. همچنین در قطع ارتباط پس از درخواست نوشتنی، نتیجه را نامعلوم در نظر بگیرید؛ ارسال دوبارهٔ کورکورانه می‌تواند رکورد تکراری بسازد.

پیشنهاد تحریریه برای مرحلهٔ بعد: شناسهٔ پایدار مبدأ، سیاست جلوگیری از تکرار، صف خطا و روش تطبیق نتیجه را قبل از نوشتن طراحی کنید. زمان‌بندی، حجم هر نوبت و معیار هشدار را با بار واقعی محیط اندازه بگیرید؛ عدد نمونهٔ این مقاله معیار ظرفیت نیست. برای آمادگی بازیابی نیز چک‌لیست آزمون بک‌آپ Odoo 19 را ببینید.

در تحویل اتصال، مسئول رسیدگی به خطا و پذیرش داده را تعیین کنید. اگر جریان شما سفارش را میان سامانه‌ها منتقل می‌کند، الگوی تحویل سفارش از فروش به اجرا به تعریف مسئول و برگشت نقص کمک می‌کند. موفقیت انتقال فنی باید به یک نتیجهٔ روشن برای کاربر کسب‌وکار متصل باشد.

معیار تحویل نخستین اتصال

خروجی این مرحله باید کوچک و قابل تکرار باشد: مقصد تأییدشده، کلید با مالک معلوم، نمونهٔ مجاز و خارج از محدوده، پاسخ بررسی‌شده و گزارش بدون راز. این شواهد را همراه نسخهٔ برنامه و تاریخ آزمون ثبت کنید. پس از تعویض کلید یا تغییر دسترسی، همان آزمون محدود را دوباره اجرا کنید.

برای بررسی اتصال Odoo با سامانهٔ سازمانی، مشخصات غیرمحرمانهٔ مبدأ و مقصد، مدل‌های لازم و نتیجهٔ مورد انتظار را از طریق تماس با آسیاپرداز مطرح کنید. کلید، رمز و خروجی کامل مخاطبان را در فرم عمومی نفرستید؛ بررسی فنی با تعریف قرارداد داده و معیار پذیرش آغاز می‌شود.