مفاتيح API
`keys.list` و`list_all` و`iterate` و`get` و`create` و`update` و`delete` و`rotate` و`revoke`، وقارئا سجل الطلبات وسجل النشاط.
كل الدوالّ
key = client.keys.create( name: "Billing sender", scopes: ["emails:send"], domainAllowlist: ["billing.acme.com"], expiresInMinutes: 60 * 24 * 90) File.write(".openemail-billing-key", key[:token]) client.keys.update(key[:id], enabled: false) rotated = client.keys.rotate(key[:id])File.write(".openemail-billing-key", rotated[:token]) client.keys.revoke(key[:id], reason: "Replaced")client.keys.delete(key[:id])create وrotate هما الاستدعاءان الوحيدان اللذان يعيدان سرًّا، في token، مرة واحدة. وتعيد كل قراءة maskedKey بدلًا منه. ويوقف update المفتاح ويشغّله عبر enabled، وهو البديل القابل للتراجع عن revoke، ولا يزيل delete إلا مفتاحًا أُبطل: فأي مفتاح آخر يعطي 409 not_revoked. وتتطلب القراءة keys:read ويتطلب كل تغيير keys:manage.
لا يعيد الـ gem محاولة create أو rotate أبدًا. فإعادة المحاولة بعد استجابة ضائعة ستصنع مفتاحًا ثانيًا، أو تُبطل السر الذي أعادته المحاولة الأولى. وتُعاد محاولة update وrevoke بعد فشل في الشبكة، لأن تكرارهما يترك المفتاح نفسه، أما delete فلا.
لا يتجاوز المستدعي أبدًا
لا ينشئ المفتاح أبدًا مفتاحًا أوسع منه ولا يصل إليه. يجب أن تبقى النطاقات والدور وانتهاء الصلاحية والوضع ونطاق الإرسال كلها داخل المفتاح المستدعي، وإلا رفع الاستدعاء OpenEmail::PermissionError بالرمز beyond_caller_authority، ويسمّي param المحور. والمفتاح المقيّد ببعض النطاقات أو العناوين لا يرى إلا المفاتيح الواقعة داخل نطاق إرساله. ويعمل rotate على المفتاح المستدعي نفسه أيضًا بـ keys:write، مثل client.me.rotate.
لا يمكن تطبيق التحقق الإضافي على استدعاء يجري بمفتاح، لذا فإن keys:manage اعتماد يصنع اعتمادات. امنحه فقط لأتمتة تصدر المفاتيح، وامنح ذلك المفتاح دورًا ونطاق إرسال وانتهاء صلاحية، وراقب list_workspace_activity حيث يُسجَّل كل ما يفعله باسمه.
سجل الطلبات والنشاط
failures = client.keys.list_requests( "4c1b257a66287fd113bd89d0", failed_only: true, since: Time.now - (24 * 60 * 60))puts failures.items.size client.keys.iterate_workspace_activity do |change| puts [change[:keyName], change[:type], change.dig(:actor, :label)].join(" ")endيقرأ list_requests وlist_activity مفتاحًا واحدًا، ويقرأ list_workspace_requests وlist_workspace_activity كل المفاتيح أو تلك التي يسمّيها key_ids:. ولكل منها توأما list_all_ وiterate_ إلى جانبه، مثل list_all_requests وiterate_requests. وتأخذ since: وuntil: بوصفهما Time أو DateTime أو سلسلة ISO 8601، ويأخذ قارئا الطلبات أيضًا failed_only:.
until كلمة محجوزة في Ruby، لكن until: يعمل كوسيط مسمّى كما هو مكتوب. ويجب أن يكون بعد since:، وإلا رفع الاستدعاء OpenEmail::InvalidRequestError بالرمز invalid_parameter.