استخدام واجهة برمجة تطبيقات الرمز المميّز لتسجيل متصفِّح Chrome

التفويض

يتم توضيح التفويض المطلوب في دليل Chrome Enterprise Core's Takeout API Service Script للوصول إلى واجهة برمجة تطبيقات الرمز المميّز للتسجيل. يحتاج المستخدمون إلى اتّباع خطوات التفويض نفسها في واجهة برمجة التطبيقات لاسترداد رمز الدخول.

ChromeEnrollmentToken

إنّ ChromeEnrollmentToken هو سلسلة (string) يُستخدَم لتحديد عملية تسجيل متصفّح Chrome.

تمثيل الموارد

يتم استخدام نموذج JSON التالي لمورد ChromeEnrollmentToken في دليل واجهة برمجة التطبيقات:

{

"kind": "admin#directory#chromeEnrollmentToken",

"orgUnitPath": string,

"token": string,

"tokenPermanentId": string,

"customerId": string,

"orgUnitPath": string,

"state": enum {
    "active",

    "expired",

    "revoked",

}

"expiration": oneof {

    "expireTime": dateTime,

    "ttl": duration

  }

"creatorId": string,

"creationTime": dateTime,

"revokerId": string,

"revokeTime": dateTime,

"tokenType": enum {

    "chromeBrowser"

  }

}

استدعاء واجهة برمجة التطبيقات

إدراج جميع الرموز المميّزة لتسجيل حساب

لإدراج جميع الرموز المميّزة لتسجيل Chrome على حساب ضِمن وحدة تنظيمية، استخدِم طلب GET التالي وأضِف رمز الدخول الذي تم الحصول عليه من خلال اتّباع قسم "التفويض". 

ملاحظة: بغرض سهولة القراءة ووضوحها، تحتوي عينة التعليمات البرمجية التالية على أحرف الرجوع إلى أول السطر.

GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens?query=
{query_string}&pageSize={number_of_results_to_return}
&pageToken={page_token_from_previous_request}&orgUnitPath={/org-unit-path}

• customerId هو معرّف فريد لحساب العميل على Google.
• عند استخدام هوية مشرف الحساب، يمكنك أيضًا استخدام السلسلة my_customer التي تمثِّل customerId لحسابك. هناك طريقة أخرى للحصول على قيمة customerId، وهي استخدام عملية استرداد مستخدم. ويمكنك استخدام عنوان البريد الإلكتروني للمشرف أو رقم التعريف الفريد للمشرف في مَعلمة مسار userKey في تلك العملية.

في ما يلي معلومات مرجعية لجميع مَعلمات الحمولة التي يمكن استخدامها في الطلب:

المَعلمة	مطلوبة	النوع	الوصف
orgUnitPath	اختيارية	سلسلة	لا تدرج هذه المَعلمة سوى الرموز المميّزة للتسجيل التي تم إنشاؤها في وحدة تنظيمية محدَّدة.  في حال عدم تحديد هذا الحقل، سيتم إدراج جميع الرموز المميّزة للتسجيل الخاصة بهذا العميل.
pageSize	اختيارية	int	تعرض هذه المَعلمة أكبر عدد ممكن من النتائج. والحد الأقصى والتلقائي هو 100 نتيجة.
pageToken	اختيارية	سلسلة	تُستخدَم مَعلمة طلب البحث pageToken في طلب الصفحة التالية من نتائج طلب البحث. مَعلمة طلب البحث pageToken لطلب المتابعة هي nextPageToken من استجابتك السابقة. ملاحظة: الطلبات التي تتضمّن الحقل page_token يجب أن تحتوى على الطلب نفسه وكذلك قيمة الحقل org_unit_path كما هو الحال مع الطلب الذي أدى إلى إنشاء page_token.
query	اختيارية	سلسلة	هذه المَعلمة عبارة عن سلسلة بحث لفلترة الرموز المميّزة المُدرجَة. ويتم وصف تنسيق لغة طلب بحث صفحة القائمة في القسم (Filter Query Language) التالي.

مثال

مثال على الطلب

GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens?pageSize=1&orgUnitPath=”/Org-unit-path”

استجابة JSON

يعرض الطلب الناجح رمز الحالة HTTP 200. وبالإضافة إلى ذلك، تعرض الاستجابة خصائص الرمز المميّز لتسجيل Chrome:

{
  kind: "admin#directory#chromeEnrollmentTokens",
  "chrome_enrollment_tokens": [
    {
      "tokenId": "token_id_value",
      "tokenPermanentId": "token_Permanent_id_value",
      "kind": "admin#directory#chromeEnrollmentToken",
      "orgUnitPath": "/Org-unit-path",
      "state": "active",
      "creator_id": “unique_id_of_user",
      "create_time": "2020-04-30T19:22:44Z",
      "tokenType": "chromeBrowser",
    }
  ],
  "nextPageToken": "abcdefghijkl123"
}

لغة فلترة طلب البحث

عند استخدام مَعلمة "طلب البحث" في طلب قائمة، يجب مطابقة كل عبارة في طلب البحث في إحدى المَعلمات التالية حتى يتم اعتبار النتائج مطابقة. يمكنك تحديد أن يتم تضييق الرموز المميزة المعروضة لتتطابق مع قيمة الحقل في العبارة. في حال عدم تحديد أي عوامل تشغيل (حقول) في طلب البحث، سيعرض البحث جميع الرموز المميّزة للتسجيل.

على سبيل المثال، إذا كان طلب البحث هو:
{URL}?query="device_type:CHROME_BROWSER+token_state:REVOKED",
سيؤدي هذا إلى عرض الرموز المميّزة للتسجيل على النحو التالي:

{
  "tokenId": "token_id_value",
  "tokenPermanentId": "token_Permanent_id_value",
  "kind": "admin#directory#chromeEnrollmentToken",
  "orgUnitPath": "/Org-unit-path",
  “tokenState”: “revoked”,
  “creatorId”: “unique_id_of_user”,
  "create_time": "2020-04-30T19:22:44Z",
  "tokenType": "chromeBrowser",
}

يمكنك تحديد الحقول التالية لتوجيه بحثك إلى حقل محدَّد:

الحقل	الوصف
device_type	يعرض هذا الحقل نوع الجهاز الذي يتم من أجله استخدام الرموز المميّزة للتسجيل. لا يتوفّر في الوقت الحالي سوى CHROME_BROWSER.
token_state	يعرض هذا الحقل حالة الرمز المميّز للتسجيل. القيم المتوفّرة هي: REVOKED وACTIVE وEXPIRED.

إنشاء الرمز المميّز للتسجيل

لإنشاء رمز مميَّز لتسجيل Chrome في وحدة تنظيمية، استخدِم طلب POST التالي وأضِف رمز الدخول الذي تم الحصول عليه من خلال اتّباع قسم "التفويض".

ملاحظة: بغرض سهولة القراءة ووضوحها، تحتوي عينة التعليمات البرمجية التالية على أحرف الرجوع إلى أول السطر.

POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens

• customerId هو معرّف فريد لحساب العميل على Google.
• عند استخدام هوية مشرف الحساب، يمكنك أيضًا استخدام السلسلة my_customer التي تمثِّل customerId لحسابك. هناك طريقة أخرى للحصول على قيمة customerId، وهي استخدام عملية استرداد مستخدم. ويمكنك استخدام عنوان البريد الإلكتروني للمشرف أو رقم التعريف الفريد للمشرف في مَعلمة مسار userKey في تلك العملية.

في ما يلي معلومات مرجعية لجميع مَعلمات الحمولة التي يمكن استخدامها في الطلب:

المَعلمة	مطلوبة	النوع	الوصف
expire_time	اختيارية	سلسلة	تعرض هذه المَعلمة وقت انتهاء صلاحية الرمز المميّز للتسجيل الذي تم إنشاؤه، بتنسيق yyyy-MM-ddThh:mm:ssZ. في حال عدم تحديد هذا الحقل، سيظل الرمز المميّز للتسجيل ساريًا إلى أن يُبطله المستخدمون.
org_unit_path	اختيارية	سلسلة	تعرض هذه المَعلمة الوحدة التنظيمية التي يتم من أجلها إنشاء رمز مميّز للتسجيل. في حال عدم تحديد هذا الحقل، سيتم إنشاء الرمز المميّز للتسجيل الخاص بالوحدة التنظيمية الأساسية.
token_type	مطلوبة	سلسلة	تعرض هذه المَعلمة نوع جهاز Chrome الذي يتم من أجله إنشاء رمز تسجيل مميّز. لا يتوفّر في الوقت الحالي سوى CHROME_BROWSER.
ttl	اختيارية	سلسلة	تعرض هذه المَعلمة صلاحية الرمز المميّز للتسجيل الذي تم إنشاؤه، ويتم ترميزه بالثواني مع إضافة اللاحقة "s". على سبيل المثال، لكي تستمر صلاحية رمز مميّز لمدة ساعة واحدة، يجب ضبط هذا الحقل على "3600s". وفي حال عدم تحديد هذا الحقل، سيظل الرمز المميّز للتسجيل ساريًا إلى أن يُبطله المستخدمون.

مثال

مثال على الطلب

POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens
{
  "token_type": "CHROME_BROWSER",
  "org_unit_path": "/org-unit-path",
  "expire_time": "2021-04-30T19:22:44Z",
}

استجابة JSON

يعرض الطلب الناجح رمز الحالة HTTP 200. وبالإضافة إلى ذلك، تعرض الاستجابة خصائص الرمز المميّز لتسجيل Chrome:

{
  "tokenId": "token_id_value",
  "tokenPermanentId": "token_Permanent_id_value",
  "kind": "admin#directory#chromeEnrollmentToken",
  "orgUnitPath": "/Org-unit-path",
  "state": "active",
  "creatorId”: "unique_id_of_user",
  "create_time": "2020-04-30T19:22:44Z",
  "expire_time": "2021-04-30T19:22:44Z",
  "tokenType": "chromeBrowser",
}

إبطال الرمز المميّز للتسجيل

لإبطال رمز مميّز للتسجيل، استخدِم طلب POST التالي وأضِف رمز الدخول الذي تم الحصول عليه من خلال اتّباع قسم "التفويض". 

ملاحظة: بغرض سهولة القراءة ووضوحها، تحتوي عينة التعليمات البرمجية التالية على أحرف الرجوع إلى أول السطر.

POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/
{my_customer|customerId}/chrome/enrollmentTokens/{tokenPermanentId}:revoke

• customerId هو معرّف فريد لحساب العميل على Google.
• عند استخدام هوية مشرف الحساب، يمكنك أيضًا استخدام السلسلة my_customer التي تمثِّل customerId لحسابك. هناك طريقة أخرى للحصول على قيمة customerId، وهي استخدام عملية استرداد مستخدم. ويمكنك استخدام عنوان البريد الإلكتروني للمشرف أو رقم التعريف الفريد للمشرف في مَعلمة مسار userKey في تلك العملية.
• tokenPermanentId هو معرّف فريد للرمز المميّز للتسجيل، ويمكن العثور عليه في الحقل "tokenPermanentId" في استجابات List أو Create.

مثال

مثال على الطلب

POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/chrome/enrollmentTokens/token_permanent_id_value:revoke

استجابة JSON

يعرض الطلب الناجح رمز الحالة HTTP 200.