پیوست کردن فایل به رکورد از داخل اسکریپت

هدف

به یک فراخوان بیرونی — یک پورتال، سامانهٔ یک شریک — اجازه دهید از طریق یک Custom API فایلی را به یک رکورد پیوست کند، به‌طوری که اسکریپت شما تصمیم بگیرد روی کدام رکورد بنشیند و آیا فراخوان اصلاً مجاز است یا نه.

چرا این وجود دارد

ستون‌های File و Image یک رکورد از قبل endpointهای خودشان را دارند و فرم از آن‌ها استفاده می‌کند. یک پورتال نمی‌تواند: پورتال فقط و فقط از طریق Custom APIها با پلتفرم حرف می‌زند، چون بررسی‌ای که یک مشتری را از رکوردهای مشتری دیگر دور نگه می‌دارد باید در اسکریپت و کنار portalCustomerId() بنشیند، نه در سازندهٔ درخواستِ یک وب‌سایت.

پس حالا یک اسکریپت می‌تواند فایلی را در فیلد یک رکورد بگذارد و دوباره بخواند. بایت‌ها به شکل متن base64 سفر می‌کنند، چون اسکریپت راه دیگری برای نگه داشتن آن‌ها ندارد — فراخوان رمز می‌کند، پلتفرم رمزگشایی می‌کند، و اسکریپت فقط رشته را رد می‌کند.

اسکریپت چه می‌تواند بکند


`putRecordFile(table, id, field, fileName, contentType, contentBase64)`	فایل را در فیلد رکورد ذخیره می‌کند. `true` برمی‌گرداند، یا `false` اگر نتوانست
`getRecordFile(table, id, field)`	فایل به شکل یک شیء — `fileName`، `contentType`، `sizeBytes`، `contentBase64` — یا هیچ اگر فیلد خالی باشد

هر دو به نام فراخوان عمل می‌کنند: ذخیره کردن به Update روی رکورد نیاز دارد و خواندن به Read، دقیقاً مثل endpointهای فایلِ خودِ رکورد. سقف اندازهٔ فیلد و قاعدهٔ «فقط تصویر» متعلق به پلتفرم است، نه اسکریپت.

مراحل

به جدول یک ستون File بدهید — par_attachment — و اگر فهرست باید نام را بدون واکشی فایل نشان دهد، یک ستون Text کنارش برای نام.
در request schema مربوط به Custom API، فایل را به شکل سه ویژگی بگیرید:
```
"attachmentName": { "type": "string", "maxLength": 260 },
"attachmentType": { "type": "string", "maxLength": 200 },
"attachmentBase64": { "type": "string", "maxLength": 5600000 }
```
یا، از دور ۱۰ درگاه‌ها به بعد، به‌شکل یک شیء — که همان چیزی است که انتخاب‌گر فایل در یک صفحهٔ کشیده‌شده می‌فرستد، و همان شکلی که getRecordFile پاسخ می‌دهد:
```
"par_document": {
  "type": "object",
  "additionalProperties": false,
  "required": ["fileName", "contentType", "contentBase64"],
  "properties": {
    "fileName":      { "type": "string", "maxLength": 260 },
    "contentType":   { "type": "string", "maxLength": 200 },
    "sizeBytes":     { "type": "integer" },
    "contentBase64": { "type": "string", "maxLength": 5600000 }
  }
}
```
آن‌گاه getInput('par_document') شیء را یکجا به اسکریپت می‌دهد و file.fileName یکی از اعضای آن را می‌خواند. اگر فراخوان یک صفحهٔ درگاه پارس‌ور است، این شکل را به‌کار ببرید — ببینید بگذارید بازدیدکنندگان فایل پیوست کنند.

در اسکریپت، اول رکورد را بسازید و بعد فایل را — فایلِ رکورد به یک رکورد تعلق دارد:

var id = createRecord('par_request', {
  par_name: getInput('subject'),
  par_attachment_name: getInput('attachmentName')
});
if (!isEmpty(getInput('attachmentBase64'))) {
  putRecordFile('par_request', id, 'par_attachment',
    getInput('attachmentName'), getInput('attachmentType'), getInput('attachmentBase64'));
}

برای برگرداندن یک فایل، اول بررسی کنید رکورد متعلق به فراخوان است و بعد بخوانید:

var file = getRecordFile('par_request', id, 'par_attachment');
if (isEmpty(file)) {
  setStatus(404);
} else {
  setOutput('fileName', file.fileName);
  setOutput('contentType', file.contentType);
  setOutput('contentBase64', file.contentBase64);
}

سه چیزی که آدم‌ها را گیر می‌اندازد

قبل از خواندن، مالکیت را بررسی کنید. getRecordFile به نام برنامهٔ فراخوان اجرا می‌شود، که چه بسا مجاز باشد همهٔ رکوردهای جدول را بخواند. پرسش «آیا این رکورد متعلق به این فراخوان است؟» پرسش اسکریپت شماست، و با خواندن رکورد و مقایسه پاسخ داده می‌شود.
نامِ روی ردیف یک عکس فوری است. ردیف فایل نام واقعی را نگه می‌دارد؛ یک ستون Text کنارش به فهرست اجازه می‌دهد بگوید «📎 report.pdf» بی‌آنکه برای هر ردیف یک فراخوانی فایل بزند. وقتی فایل را ذخیره می‌کنید آن را بنویسید، و تا وقتی کسی فایل را از درِ دیگری عوض نکرده درست می‌ماند.
فایل‌های بزرگ از داخل اسکریپت رد نمی‌شوند. فایلی بزرگ‌تر از سقف فیلد در object storage ذخیره می‌شود و endpoint رکورد آن را استریم می‌کند؛ getRecordFile به جای مادی کردن صدها مگابایت داخل یک مفسر، آن را رد می‌کند.

تأیید کنید که کار کرد

رکورد را در برنامه‌اش باز کنید: ستون File فایل را نشان می‌دهد، و دانلود آن همان چیزی را برمی‌گرداند که فراخوان فرستاده بود. تاریخچهٔ ممیزی تغییر را با نام و هش فایل ثبت می‌کند.

عیب‌یابی

«expects the file's content as base64 text; what was passed does not decode.» فراخوان بایت‌های خام فرستاده، یا یک data URL که هنوز پیشوند data:…;base64, رویش است. فقط base64 را بفرستید.

«The file is N bytes; the limit for this field is M bytes.» بزرگ‌تر از سقف، و هیچ object storageای برای سرریز پیکربندی نشده است. از فراخوان چیزی کوچک‌تر بخواهید، یا یک باکت سرریز پیکربندی کنید.

«cannot carry a N-byte file; a script reads files up to M bytes.» فایل به object storage سرریز شده است. آن را از طریق endpoint فایلِ رکورد ارائه دهید، که استریم می‌کند.

هدف​

چرا این وجود دارد​

اسکریپت چه می‌تواند بکند​

مراحل​

سه چیزی که آدم‌ها را گیر می‌اندازد​

تأیید کنید که کار کرد​

عیب‌یابی​

هدف