الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

واجهة برمجة التطبيقات العامة لتسجيل الدخول إلى DfE

واجهة برمجة التطبيقات (API) للمستهلكين الخارجيين للتفاعل مع تسجيل الدخول إلى DfE

تحتاج إلى المصادقة باستخدام واجهات برمجة التطبيقات هذه

لاستخدام أي من واجهات برمجة التطبيقات أدناه، ستحتاج إلى توفير رمز حامل في رأس الطلب، وهذا الرمز المميز للحامل هو مجرد JWT (راجع https://jwt.io) مع حمولة بسيطة تم توقيعها باستخدام سر فقط DfE تسجيل الدخول وأنت تعلم.

يجب عليك إنشاء JWT عند نقطة الاستخدام في تطبيق الاتصال الخاص بك باستخدام مكتبة JWT القياسية التي تأتي مع التكنولوجيا التي اخترتها.

سيتطلب نص الرمز المميز والمصدر (معرف عميل الخدمة الخاص بك) والجمهور على النحو التالي: 

{
  "iss": "REPLACE_WITH_YOUR_CLIENT_ID",
  "aud": "signin.education.gov.uk"
}

يجب توقيع الرمز المميز باستخدام خوارزمية HS256 مع API_SECRET الخاص بك. عند نقطة التكامل مع تسجيل الدخول إلى DfE، سيتم منحك API_SECRET (يجب عدم الخلط بينه وبين CLIENT_SECRET الخاص بك)، إذا لم يكن لديك هذا، فاتصل بفريق تسجيل الدخول إلى DfE وسنقوم بإعادة إنشاء واحد لك (هذه هي خدمة/بيئة محددة.)

استخدام Postman لتقييم واختبار واجهات برمجة التطبيقات

نظرة عامة على ساعي البريد

Postman هي أداة منصة API تستخدم لإنشاء وتنفيذ واجهات برمجة التطبيقات. يعمل Postman على تبسيط كل خطوة من دورة حياة واجهة برمجة التطبيقات (API) ويتم استخدامه على نطاق واسع في تطوير وتوثيق واجهة برمجة تطبيقات DfE العامة لتسجيل الدخول.

تم توفير مجموعة من مجموعات Postman وبيئات التنفيذ المرتبطة بها لمساعدتك على تعلم واختبار وتصحيح عمليات التكامل مع النظام الأساسي لتسجيل الدخول إلى DfE عبر واجهة برمجة التطبيقات العامة.

بدء استخدام Postman ومجموعة تسجيل الدخول إلى DfE

تتوفر أدوات النظام الأساسي لـ Postman API كعميل سطح مكتب وتطبيق ويب مستضاف وواجهة سطر أوامر (CLI) على https://www.postman.com/api-platform/api-client/.

تتوفر مجموعة وبيئات Postman API العامة لتسجيل الدخول إلى DfE على https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/.

دعوة المستخدم

باعتبارك خدمة مدمجة لتسجيل الدخول إلى DfE، يمكنك استخدام واجهة برمجة التطبيقات لدعوة المستخدمين إلى الخدمة.

يبدو الطلب 

POST https://environment-url/services/{service-id}/invitations
Authorization: bearer {jwt-token}

{
    "sourceId": "user_id_in_your_service",
	"given_name": "John",
	"family_name": "Smith",
	"email": "[email protected]",
	"callback": "https://me.service.url/users/signup-complete"
}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
معرف الخدمة عنوان URL ي معرف تسجيل الدخول إلى DfE للخدمة التي تدعو المستخدم إليها
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك
معرف المصدر جسم ي معرف المستخدم في نظامك. سيتم تضمينها في استجابة القناة الخلفية
أعطيت_اسم جسم ي المستخدمين الاسم المحدد
Family_name جسم ي اسم عائلة المستخدم
بريد إلكتروني جسم ي عنوان البريد الإلكتروني للمستخدم. يعد هذا أيضًا معرفًا فريدًا للمستخدم في تسجيل الدخول إلى DfE
منظمة جسم
 معرف تسجيل الدخول إلى DfE الذي يجب أن يرتبط به المستخدم
أتصل مرة أخرى جسم
 عنوان URL الذي يجب إرسال استجابة القناة الخلفية إليه. انظر تفاصيل استجابة القناة الخلفية أدناه
إعادة توجيه المستخدم جسم
 عنوان URL الذي يجب إرجاع المستخدم إليه عند الانتهاء، إذا كان يمر بعملية الإعداد. إذا تم حذفه، فسيتم استخدام إعادة التوجيه الافتراضية لعميلك
this.invitSubjectOverride جسم
 يتجاوز موضوع رسالة البريد الإلكتروني للدعوة
this.invitBodyOverride جسم
 يتجاوز محتوى رسالة الدعوة الإلكترونية

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
202 لقد تم قبول طلبك
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
401 JWT الخاص بك مفقود أو غير صالح.
404 معرف الخدمة في uri غير موجود
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة

عند تقديم الطلب، قد يكون المستخدم موجودًا أو لا يكون موجودًا في النظام؛ وقد يكون أو لا يكون لديه التنظيم المطلوب وتعيينات الخدمة المطلوبة. ولهذا السبب، يتم إرسال جميع تفاصيل المستخدم عبر استجابة القناة الخلفية. يمكن أن يحدث هذا على الفور إذا تم العثور على المستخدم (عن طريق البريد الإلكتروني) في تسجيل الدخول إلى DfE؛ أو بمجرد قبول المستخدم لرسالة البريد الإلكتروني التي سيتم إرسالها إليه.

تبدو استجابة القناة الخلفية كما يلي: 

POST https://callback.url/from/request
Authorization: bearer {jwt-token}

{
    "sub": "some-uuid",
    "sourceId: "source-id-from-request"
}

عناصر البيانات في الطلب هي:

اسم موقع وصف
jwt-token رأس رمز jwt، موقع بنفس سر الطلب
الفرعية جسم معرف تسجيل دخول DfE للمستخدم. لن يتغير هذا وسيتم تضمينه في رد OIDC كمطالبة فرعية
معرف المصدر جسم معرف المصدر المستخدم في الطلب الأصلي

إدارة الإعلانات

يمكن نشر الإعلانات أو عدم نشرها للمنظمة.

يمكن نشر الإعلانات عن طريق: 

POST https://environment-url/organisations/announcements
Authorization: bearer {jwt-token}

{
    "messageId": "your-unique-idenitifer",
	"urn": "12345",
	"type": 1,
	"title": "Title of announcement",
	"summary": "summary of announcement",
	"body": "body of announcement",
	"publishedAt": "2019-01-31T20:30:40Z",
	"expiresAt": "2020-01-31T20:30:40Z"
}

هيكل الإعلان هو كما يلي:

يصف مطلوب وصف يكتب
معرف الرسالة ي معرف الرسالة في النظام الأصلي. يجب أن تكون فريدة من نوعها UUID
جرة ص (أو معرف) URN للمؤسسة رقمي
uid ص (أو جرة) معرف المجموعة UUID
يكتب ي رمز النوع الرقمي للرسالة (انظر أدناه) عدد صحيح
عنوان ي عنوان الإعلان. الحد الأقصى لعدد الأحرف هو 255 نص أو HTML
ملخص ي ملخص الإعلان. الحد الأقصى لعدد الأحرف 340 نص أو HTML
جسم ي متن الإعلان. الحد الأقصى لعدد الأحرف 5000 نص أو HTML
نشرت في ي إعلان التاريخ/الوقت المنشور في ISO8601
تنتهي في
 يجب أن ينتهي إعلان التاريخ/الوقت عند ISO8601

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
202 لقد تم قبول طلبك
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
401 JWT الخاص بك مفقود أو غير صالح.
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة

أنواع الإعلانات الصالحة هي:

شفرة معنى
1 تحذير بشأن سجل المنشأة
2 مشكلة في سجل المنشأة
4 تحذير بشأن سجل الحوكمة
5 مشكلة في سجل الحوكمة

يمكن لاحقًا إلغاء نشر الإعلانات من خلال: 

DELETE https://environment-url/organisations/announcements/your-unique-idenitifer
Authorization: bearer {jwt-token}

حيث يكون your-unique-idenitifer هو معرف الرسالة الذي تم إرساله عند نشر الرسالة.

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
204 لم يتم نشر الإعلان
401 JWT الخاص بك مفقود أو غير صالح.
404 معرف الرسالة في uri غير موجود
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة

إنشاء تطبيقات فرعية

إذا تم تمكين تطبيقك، فستتمكن من إنشاء تطبيقات فرعية من خلال واجهة برمجة التطبيقات (API). هذه التطبيقات الفرعية مخصصة للاستخدام عندما يكون لديك تطبيقات تابعة لجهات خارجية ستستخدم تدفق موافقة OIDC لتمكينها من استدعاء واجهة برمجة التطبيقات (API) داخل التطبيق الخاص بك في سياق المستخدم.

يمكن إنشاء التطبيقات التابعة عن طريق: 

POST https://environment-url/services
Authorization: bearer {jwt-token}

{
	"name": "The display name of the application",
	"description": "A description of what the application does",
	"consentTitle": "Override for the content at the top of the Consent Screen",
	"consentBody": "Override for the content of the Consent Screen",
	"redirectUris": [
	    "https://endpoint.one/auth/cb",
	    "https://endpoint.two/login/callback"
	]
}

ملاحظة حول تجاوزات قالب الموافقة
تسمح المعلمتان بتجاوز المحتوى المعروض للمستخدمين في شاشة الموافقة، والعنوان والنص (كل شيء آخر ثابت وفقًا لتصميم النموذج الحالي). قيمة التجاوز هي سلسلة تحتوي على قيمتين ديناميكيتين (اختياريتين). على سبيل المثال، consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"

هيكل التطبيق هو كما يلي:

يصف مطلوب وصف
اسم ي اسم سهل الاستخدام للتطبيق. سيتم استخدام هذا عند مطالبة المستخدم بالموافقة
وصف ن وصف للتطبيق
redirectUris ي مصفوفة من Uris لإعادة التوجيه التي يمكن استخدامها أثناء تدفق تسجيل الدخول/الموافقة لـ OIDC

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
201 تم إنشاء تطبيق طفلك
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
403 ليس لدى التطبيق الخاص بك إذن لإنشاء تطبيقات فرعية

عند إنشاء تطبيق فرعي بنجاح، ستتلقى ردًا مثل: 

{
	"name": "The display name of the application",
	"description": "A description of what the application does",
	"clientId": "child-application-clientid",
	"clientSecret": "child-application-clientsecret",
	"redirectUris": [
	    "https://endpoint.one/auth/cb",
	    "https://endpoint.two/login/callback"
	]
}

يعد name description redirectUris بمثابة تأكيد لما تم استلامه من طلبك. إن clientId و clientSecret هما ما سيحتاج التطبيق الفرعي إلى استخدامه عند تنفيذ عمليات OIDC. ستحتاج أيضًا إلى clientId لأي إدارة لاحقة للتطبيق.

إذا تم اختراق سر تطبيق فرعي، فيمكنك طلب إعادة إنشاء السر عن طريق: 

POST https://environment-url/services/client-id-of-child-application/regenerate-secret
Authorization: bearer {jwt-token}

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
200 لقد تم تجديد السر
403 معرف العميل المحدد ليس تابعًا لتطبيقك
404 لا يمكن العثور على أي تطبيق بمعرف العميل المحدد

عند تجديد السر بنجاح، سوف تتلقى ردًا مثل: 

{
    "clientSecret": "regenerated-client-secret"
}

منح ورموز تطبيق الطفل

تتبع طلبات الأطفال تدفق الموافقة الصريحة الذي ينتج عنه في النهاية رمز التفويض (منحة) والذي يمكن استبداله برمز وصول قصير الأمد ورمز تحديث طويل الأمد، من أجل السماح لأصحاب التطبيقات الفرعية بإدارة دورة حياة الرموز المميزة الصادرة التي نقدمها واجهة برمجة تطبيقات ملائمة لسرد المنح ومشكلات الرموز المميزة لتطبيق تابع حكومي.

يمكن بعد ذلك فحص هذه الرموز المميزة وإبطالها باستخدام نقاط النهاية القياسية لاتصال المعرف المفتوح (الاستبطان والإلغاء).

للحصول على قائمة المنح لخدمة معينة للطفل: 

GET https://environment-url/services/{service-id}/grants

للحصول على قائمة بالرموز الصادرة لمنحة خدمة طفل معينة: 

GET https://environment-url/services/{service-id}/grants/{grant-id}/tokens

الحصول على وصول المستخدم إلى الخدمة

يمكنك استخدام واجهة برمجة التطبيقات هذه للحصول على وصول المستخدم إلى خدمة لمؤسسة ما. يبدو الطلب 

GET https://environment-url/services/{service-id}/organisations/{organisation-id}/users/{user-id}
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
معرف الخدمة عنوان URL ي معرف تسجيل الدخول DfE للخدمة
معرف المنظمة عنوان URL ي معرف تسجيل الدخول إلى DfE للمؤسسة
معرف المستخدم عنوان URL ي معرف تسجيل الدخول إلى DfE للمستخدم
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك

سيؤدي هذا إلى إرجاع استجابة بالتنسيق التالي 

{
    "userId": "user-id",
    "serviceId": "service-id",
    "organisationId": "organisation-id",
    "roles": [
        {
            "id": "role-id",
            "name": "The name of the role",
            "code": "The code of the role",
            "numericId": "9999",
            "status": {
                "id": 1
            }
        }
    ],
    "identifiers": [
        {
            "key": "identifier-key",
            "value": "identifier-value"
        }
    ]
}

ملاحظة: إذا لم يكن لدى المستخدم الخدمة المحددة أو لم يكن موجودًا في المؤسسة المذكورة، فسوف يُرجع رمز الحالة 404 (غير موجود) .

الحصول على المنظمات للمستخدم

يمكنك استخدام واجهة برمجة التطبيقات هذه للحصول على المؤسسات المرتبطة بمستخدم يبدو الطلب 

GET https://environment-url/users/{user-id}/organisations
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
معرف المستخدم عنوان URL ي معرف تسجيل الدخول إلى DfE للمستخدم
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك

سيؤدي هذا إلى إرجاع استجابة بالتنسيق التالي 

[
    {
        "id": "org-id",
        "name": "Organisation name",
        "category": {
            "id": "004",
            "name": "Early Year Setting"
        },
        "urn": "org-urn",
        "uid": null,
        "ukprn": null,
        "establishmentNumber": null,
        "status": {
            "id": 1,
            "name": "Open"
        },
        "closedOn": null,
        "address": null,
        "telephone": null,
        "statutoryLowAge": null,
        "statutoryHighAge": null,
        "legacyId": "legacy-id",
        "companyRegistrationNumber": null
    },
]

الحصول على الأدوار للخدمة

يمكنك استخدام نقطة نهاية واجهة برمجة التطبيقات هذه للحصول على الأدوار المرتبطة بخدمتك، أو إحدى خدمات طفلك. يبدو الطلب كالتالي: 

GET https://environment-url/services/{client-id}/roles
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
معرف العميل عنوان URL ي معرف عميل تسجيل الدخول إلى DfE للخدمة
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
200 تم استرداد قائمة الأدوار (ربما تكون فارغة) بنجاح لمعرف العميل المطلوب.
403 معرف العميل المحدد ليس خدمتك، أو تابع لخدمتك.
404 لا يمكن العثور على خدمة بمعرف العميل المحدد.

سيعيد هذا الرد بالتنسيق التالي: 

[
    {
        "name": "Role 1 Name",
        "code": "Role1Code",
        "status": "Active"
    },
    {
        "name": "Role 2 Name",
        "code": "Role2Code",
        "status": "Inactive"
    }
]

أو ما يلي إذا لم يتم العثور على الأدوار: 

[]

احصل على مؤسسات للمستخدم بما في ذلك سمات مؤسسة ملف تعريف الموفر

يمكنك استخدام واجهة برمجة التطبيقات هذه للحصول على المؤسسات المرتبطة بمستخدم يبدو الطلب 

GET https://environment-url/users/{user-id}/v2/organisations
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
معرف المستخدم عنوان URL ي معرف تسجيل الدخول إلى DfE للمستخدم
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك

سيؤدي هذا إلى إرجاع استجابة بالتنسيق التالي 

[
    {
        "id": "org-id",
        "name": "Organisation name",
        "category": {
            "id": "001",
            "name": "Establishment"
        },
        "urn": null,
        "uid": null,
        "upin": "111111",
        "ukprn": "21133510",
        "establishmentNumber": null,
        "status": {
            "id": 1,
            "name": "Open"
        },
        "closedOn": null,
        "address": "Organisation address",
        "telephone": null,
        "statutoryLowAge": null,
        "statutoryHighAge": null,
        "legacyId": "1111",
        "companyRegistrationNumber": null,
        "DistrictAdministrativeCode": null,
        "DistrictAdministrative_code": null,
        "providerTypeName": "Commercial and Charitable Provider",
        "ProviderProfileID": "7777777",
        "OpenedOn": null,
        "SourceSystem": "PIMS",
        "GIASProviderType": null,
        "PIMSProviderType": "Private Limited Company",
        "PIMSProviderTypeCode": 11,
        "PIMSStatus": "1",
        "masteringCode": null,
        "PIMSStatusName": "",
        "GIASStatus": null,
        "GIASStatusName": null,
        "MasterProviderStatusCode": 1,
        "MasterProviderStatusName": "Active",
        "LegalName": "Org Legal Name"
    },
]

مستخدمو الخدمة بدون مرشحات

يمكنك الحصول على قائمة بالمستخدمين بدون مرشحات كما هو محدد في رمز التفويض (سمة iss)
يبدو الطلب كالتالي: 

GET https://environment-url/users?page=1&pageSize=25
Authorization: bearer {jwt-token}

تعد متغيرات الصفحة وpageSize اختيارية وتكون افتراضية 1 و25 على التوالي، وتسمح هذه المتغيرات للمتصل بالتكرار على صفحات النتائج (باستخدام السمات الموجودة في نص الاستجابة لحساب عدد السجلات والصفحات).

يحتوي نص الاستجابة على السمات التالية (مثال للإجابة أدناه):

اسم وصف
المستخدمين مجموعة من تفاصيل المستخدم (بما في ذلك كائن مؤسسة فرعي)
numberOfRecords إجمالي عدد السجلات المبلغ عنها
صفحة رقم الصفحة الحالية
numberOfPages إجمالي عدد الصفحات

مثال الاستجابة

 { "المستخدمون": [
        { "approvedAt": "2019-06-19T15:09:58.683Z"، "updatedAt": "2019-06-19T15:09:58.683Z"، "المؤسسة": { "id": "13F20E54-79EA-4146 -8E39-18197576F023"، "الاسم": "قسم التعليم"، "الفئة": "002"، "النوع": خالي، "URN": خالي، "UID": خالي، "UKPRN": خالي، "رقم المؤسسة": "001"، "الحالة": 1، "ClosedOn": null، "Address": null، "phaseOfEducation": null، "statutoryLowAge": null، "statutoryHighAge": خالية، "الهاتف": خالية، "رمز المنطقة": فارغة، "legacyId": "1031237"، "companyRegistrationNumber": "1234567"، "ProviderProfileID": ""، "UPIN": ""، "PIMSProviderType": "Central" الإدارة الحكومية"، "PIMSStatus": ""، "DistrictAdministratorName": ""، "OpenedOn": "2007-09-01T00:00:00.0000000Z"، "SourceSystem": ""، "ProviderTypeName": "Government Body"، "GIASProviderType": ""، "PIMSProviderTypeCode": ""، "createdAt": "2019- 02-20T14:27:59.020Z"، "تم التحديث": "2019-02-20T14:28:38.223Z"
            }، "roleName": "Approver"، "roleId": 10000، "userId": "21D62132-6570-4E63-9DCB-137CC35E7543"، "userStatus": 1، "email": "[email protected]"، "اسم العائلة": "جونسون"، "الاسم المعطى": "روجر"
        }
    ]، "numberOfRecords": 1، "page": 1، "numberOfPages": 1}

مستخدمي الخدمة مع المرشحات

يمكنك الحصول على قائمة بالمستخدمين الذين لديهم عوامل التصفية كما هو محدد في رمز التفويض (سمة iss)
يبدو الطلب كالتالي: 

GET https://environment-url/users?page=1&pageSize=25&status=0&from=2021%2F02%2F11%2002%3A22%3A06&to=2021%2F11%2F03%2002%3A22%3A06
Authorization: bearer {jwt-token}

تعد متغيرات الصفحة وpageSize اختيارية وتكون افتراضية 1 و25 على التوالي، وتسمح هذه المتغيرات للمتصل بالتكرار على صفحات النتائج (باستخدام السمات الموجودة في نص الاستجابة لحساب عدد السجلات والصفحات). الحالة، من وإلى هي حالة اختيارية تقبل 0 في الوقت الحالي. نطاق التاريخ يقبل 7 أيام فقط، ويجب أن تكون التواريخ في شكل مشفر بعنوان URL كما هو موضح في المثال

التحقق من صحة النطاق الزمني إرسال رسالة خطأ عندما يكون النطاق الزمني أكثر من 7 أيام. فقط من التاريخ الموجود في الفلتر يتم تحديث المستخدمين بعد 7 أيام من التاريخ. فقط حتى الآن في الفلتر يتم تحديث المستخدمين قبل 7 أيام من التاريخ. عند عدم تحديد تاريخ، يتم تحديث المستخدمين من الآن إلى 7 أيام قبل ذلك.

يحتوي نص الاستجابة على السمات التالية (مثال للإجابة أدناه):

اسم وصف
المستخدمين مجموعة من تفاصيل المستخدم (بما في ذلك كائن مؤسسة فرعي)
numberOfRecords إجمالي عدد السجلات المبلغ عنها
صفحة رقم الصفحة الحالية
numberOfPages إجمالي عدد الصفحات
تحذير (اختياري) يظهر فقط عند جلب 7 أيام فقط من المستخدمين

مثال الاستجابة

 { "المستخدمون": [
        { "approvedAt": "2019-06-19T15:09:58.683Z"، "updatedAt": "2019-06-19T15:09:58.683Z"، "المؤسسة": { "id": "13F20E54-79EA-4146 -8E39-18197576F023"، "الاسم": "قسم التعليم"، "الفئة": "002"، "النوع": خالي، "URN": خالي، "UID": خالي، "UKPRN": خالي، "رقم المؤسسة": "001"، "الحالة": 1، "ClosedOn": null، "Address": null، "phaseOfEducation": null، "statutoryLowAge": null، "statutoryHighAge": خالية، "الهاتف": خالية، "رمز المنطقة": فارغة، "legacyId": "1031237"، "companyRegistrationNumber": "1234567"، "ProviderProfileID": ""، "UPIN": ""، "PIMSProviderType": "Central" الإدارة الحكومية"، "PIMSStatus": ""، "DistrictAdministratorName": ""، "OpenedOn": "2007-09-01T00:00:00.0000000Z"، "SourceSystem": ""، "ProviderTypeName": "Government Body"، "GIASProviderType": ""، "PIMSProviderTypeCode": ""، "createdAt": "2019- 02-20T14:27:59.020Z"، "تم التحديث": "2019-02-20T14:28:38.223Z"
            }، "roleName": "Approver"، "roleId": 10000، "userId": "21D62132-6570-4E63-9DCB-137CC35E7543"، "userStatus": 1، "email": "[email protected]"، "اسم العائلة": "جونسون"، "الاسم المعطى": "روجر"
        }
    ]، "numberOfRecords": 1، "page": 1، "numberOfPages": 1، "warning": "يمكن جلب البيانات لمدة 7 أيام فقط"}

لتفسير معرف الفئة، انظر هنا.

المعتمدون للمنظمات

يمكنك الحصول على قائمة المعتمدين للمؤسسات التي تقع ضمن نطاق خدماتك (استنادًا إلى شروط سياسة الدور) إذا كانت خدمتك لديها إذن للقيام بذلك.

يبدو الطلب كالتالي: 

GET https://environment-url/users/approvers?page=1&pageSize=25
Authorization: bearer {jwt-token}

تعد متغيرات الصفحة وpageSize اختيارية وتكون افتراضية 1 و25 على التوالي، وتسمح هذه المتغيرات للمتصل بالتكرار على صفحات النتائج (باستخدام السمات الموجودة في نص الاستجابة لحساب عدد السجلات والصفحات).

يحتوي نص الاستجابة على السمات التالية (مثال للإجابة أدناه):

اسم وصف
المستخدمين مجموعة من تفاصيل المستخدم (بما في ذلك كائن مؤسسة فرعي)
numberOfRecords إجمالي عدد السجلات المبلغ عنها
صفحة رقم الصفحة الحالية
numberOfPages إجمالي عدد الصفحات

مثال الاستجابة

رموز الاستجابة المحتملة هي:

رمز حالة HTTP سبب
200 لقد تم قبول طلبك
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
401 JWT الخاص بك مفقود أو غير صالح.
403 لا يتمتع تطبيقك بالإذن للحصول على الموافقين للمؤسسات
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة
 { "المستخدمون": [
        { "المنظمة": { "المعرف": "13F20E54-79EA-4146-8E39-18197576F023"، "الاسم": "إدارة التعليم"، "الفئة": { "المعرف": "002"، "الاسم": " السلطة المحلية"
                }، "urn": null، "uid": null، "ukprn": null، "entermentNumber": "001"، "status": { "id": 1، "name": "Open"
                }، "closedOn": null، "address": null، "telephone": null، "statutoryLowAge": null، "statutoryHighAge": null، "legacyId": "1031237"، "companyRegistrationNumber": "1234567"، "ProviderProfileID" ": ""، "UPIN": ""، "PIMSProviderType": "إدارة الحكومة المركزية"، "PIMSStatus": ""، "DistrictAdministratedName": ""، "OpenedOn": "2007-09-01T00:00:00.0000000Z"، "SourceSystem": ""، "ProviderTypeName": "الهيئة الحكومية"، "GIASProviderType" : ""، "PIMSProviderTypeCode": ""
            }، "roleId": 10000، "roleName": "Approver"، "userId": "21D62132-6570-4E63-9DCB-137CC35E7543"، "userStatus": 1، "email": "[email protected]"، "اسم العائلة": "جونسون"، "الاسم المعطى": "روجر"
        }
    ]، "numberOfRecords": 1، "page": 1، "numberOfPages": 1}

احصل على مستخدمي المؤسسة حسب الأدوار باستخدام UKPRN

يمكنك استخدام واجهة برمجة التطبيقات هذه لجعل مستخدمي المؤسسات يقومون بالتصفية حسب الأدوار التي يبدو عليها الطلب 

GET https://environment-url/organisations/{UKPRN}/users?roles=role1,role2
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
UKPRN عنوان URL ي UKPRN للمنظمة
الأدوار عنوان URL ن رموز دور المستخدم لتصفية قائمة مستخدمي المؤسسة
jwt-token رأس ي يجب توقيع رمز JWT المميز للتخويل باستخدام سر واجهة برمجة التطبيقات (API) الخاص بك، والذي سيتم توفيره لك

تتضمن رموز الاستجابة المحتملة ما يلي:

رمز حالة HTTP سبب
200 تم استرداد الأدوار بنجاح للمؤسسة المطلوبة
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
401 JWT الخاص بك مفقود أو غير صالح
403 يفتقر تطبيقك إلى إذن لاسترداد المستخدمين لهذه المؤسسة
404 لم يتم العثور على أي مستخدمين لديهم الأدوار المحددة للمؤسسة المطلوبة، مما أدى إلى ظهور مصفوفة فارغة
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة

سيؤدي هذا إلى إرجاع استجابة بالتنسيق التالي 

{
    "ukprn": "organisation-ukprn-id",
    "users": [
        {
            "email": "[email protected]",
            "firstName": "user1",
            "lastName": "test",
            "userStatus": 1,
            "roles": [
                "role1"
            ]
        },
        {
            "email": "[email protected]",
            "firstName": "user2",
            "lastName": "test",
            "roles": [
                "role1",
                "role2"
            ]
        }
    ]
}

استرداد مستخدمي المؤسسة حسب المعايير التي تمت تصفيتها

يمكنك أيضًا استخدام واجهة برمجة التطبيقات المذكورة أعلاه لاسترداد مستخدمي المؤسسة بناءً على معايير تمت تصفيتها مثل عنوان البريد الإلكتروني أو معرف المستخدم. يبدو الطلب 

GET https://environment-url/organisations/{UKPRN}/[email protected]
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
UKPRN عنوان URL ي UKPRN للمنظمة
بريد إلكتروني عنوان URL ن عنوان البريد الإلكتروني للمستخدم للتصفية
jwt-token رأس ي يجب توقيع رمز JWT المميز للتفويض باستخدام سر API الخاص بك، والذي سيتم توفيره لك

يظل تنسيق الاستجابة كما هو في استدعاء واجهة برمجة التطبيقات السابق، مما يسمح بالتصفية حسب معايير محددة.

احصل على مستخدمي المؤسسة حسب الأدوار باستخدام UPIN

يمكنك استخدام واجهة برمجة التطبيقات هذه لجعل مستخدمي المؤسسات يقومون بالتصفية حسب الأدوار التي يبدو عليها الطلب 

GET https://environment-url/organisations/{UPIN}/users?roles=role1,role2
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
يوبين عنوان URL ي UPIN للمنظمة
الأدوار عنوان URL ن رموز دور المستخدم لتصفية قائمة مستخدمي المؤسسة
jwt-token رأس ي يجب توقيع رمز JWT المميز للتفويض باستخدام سر API الخاص بك، والذي سيتم توفيره لك

تتضمن رموز الاستجابة المحتملة ما يلي:

رمز حالة HTTP سبب
200 تم استرداد الأدوار بنجاح للمؤسسة المطلوبة
400 طلبك غير صالح. سيتم توفير تفاصيل إضافية في نص الاستجابة
401 JWT الخاص بك مفقود أو غير صالح
403 يفتقر تطبيقك إلى إذن لاسترداد المستخدمين لهذه المؤسسة
404 لم يتم العثور على أي مستخدمين لديهم الأدوار المحددة للمؤسسة المطلوبة، مما أدى إلى ظهور مصفوفة فارغة
500 حدث خطأ على الخادم. يرجى التأكد من تكوين الأسرار مثل الأسرار أو مفاتيح API أو الرموز المميزة بشكل صحيح. إذا استمرت المشكلة، يرجى الاتصال بفريق الدعم للحصول على المساعدة

سيؤدي هذا إلى إرجاع استجابة بالتنسيق التالي 

{
    "upin": "organisation-upin-id",
    "users": [
        {
            "email": "[email protected]",
            "firstName": "user1",
            "lastName": "test",
            "userStatus": 1,
            "roles": [
                "role1"
            ]
        },
        {
            "email": "[email protected]",
            "firstName": "user2",
            "lastName": "test",
            "roles": [
                "role1",
                "role2"
            ]
        }
    ]
}

استرداد مستخدمي المؤسسة حسب المعايير التي تمت تصفيتها

يمكنك أيضًا استخدام واجهة برمجة التطبيقات المذكورة أعلاه لاسترداد مستخدمي المؤسسة بناءً على معايير تمت تصفيتها مثل عنوان البريد الإلكتروني أو معرف المستخدم. يبدو الطلب 

GET https://environment-url/organisations/{UPIN}/[email protected]
Authorization: bearer {jwt-token}

عناصر البيانات المتغيرة هي:

اسم موقع مطلوب وصف
يوبين عنوان URL ي UPIN للمنظمة
بريد إلكتروني عنوان URL ن عنوان البريد الإلكتروني للمستخدم للتصفية
jwt-token رأس ي يجب توقيع رمز JWT المميز للتفويض باستخدام سر API الخاص بك، والذي سيتم توفيره لك

يظل تنسيق الاستجابة كما هو في استدعاء واجهة برمجة التطبيقات السابق، مما يسمح بالتصفية حسب معايير محددة.

كيف يتم تعيين معرفات للفئات والأنواع؟

فئات المنظمة

بطاقة تعريف وصف
001 المنشأة (انظر أنواع المنشآت أدناه)
002 السلطة المحلية
003 المنظمات التراثية الأخرى
004 إعداد السنة المبكرة
008 أصحاب المصلحة الآخرين
009 مقدمو التدريب
010 صندوق متعدد الأكاديميات
011 حكومة
012 أصحاب المصلحة الآخرون في GIAS
013 ثقة الأكاديمية الواحدة
050 موردي البرمجيات
051 التعليم الإضافي

أنواع المنشأة

بطاقة تعريف وصف
001 مدرسة المجتمع
002 مدرسة المساعدة التطوعية
003 المدرسة التطوعية الخاضعة للرقابة
005 مدرسة التأسيس
006 كلية المدينة التكنولوجية
007 مدرسة المجتمع الخاصة
008 مدرسة خاصة غير خاضعة للصيانة
010 مدرسة خاصة مستقلة أخرى
011 مدرسة مستقلة أخرى
012 مدرسة المؤسسة الخاصة
014 وحدة إحالة التلاميذ
015 مدرسة حضانة لوس أنجلوس
018 التعليم الإضافي
024 الوحدات الآمنة
025 المدارس الخارجية
026 خدمة تعليم الأطفال
027 متنوعة
028 الراعي الأكاديمية بقيادة
029 مؤسسة التعليم العالي
030 المؤسسة الويلزية
031 مراكز النموذج السادس
032 مؤسسة المشاركة الخاصة 16
033 الراعي الخاص للأكاديمية بقيادة
034 محول الأكاديمية
035 المدارس المجانية
036 المدارس المجانية الخاصة
037 المدارس البريطانية في الخارج
038 المدارس المجانية – توفير بديل
039 المدارس المجانية - 16-19
040 الكلية التقنية بالجامعة
041 مدارس الاستوديو
042 محول توفير الأكاديمية البديلة
043 أكاديمية توفير الراعي البديل بقيادة
044 أكاديمية محول خاص
045 أكاديمية 16-19 محول
046 أكاديمية 16-19 الراعي بقيادة
047 أطفال
يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل