إنشاء موصِّل هوية

تتعرّف خدمة Google Cloud Search تلقائيًا على هويات Google المُخزَّنة في "دليل Google Cloud" فقط (المستخدمون والمجموعات). يتم استخدام موصِّلات الهوية لمزامنة هويات مؤسستك مع هويات Google التي يستخدمها Google Cloud Search.

توفِّر Google الخيارات التالية لتطوير موصِّلات الهوية:

  • حزمة تطوير البرامج (SDK) لموصل الهوية. هذا الخيار مخصص للمطورين الذين يبرمجون لغة برمجة Java. حزمة SDK لـ Identity Connector هي أداة تضمين حول واجهة برمجة تطبيقات REST تتيح لك إنشاء الموصلات بسرعة. لإنشاء موصِّل هوية باستخدام حزمة تطوير البرامج (SDK)، يمكنك الرجوع إلى إنشاء موصِّل هوية باستخدام Identity Connector SDK.

  • واجهة برمجة تطبيقات REST API ومكتبات واجهة برمجة تطبيقات منخفضة المستوى. هذه الخيارات مخصصة للمطورين الذين قد لا يبرمجون بلغة Java أو لديهم قاعدة تعليمات برمجية تتلاءم بشكل أفضل مع واجهة برمجة تطبيقات RST أو مكتبة. لإنشاء موصِّل هوية باستخدام واجهة برمجة تطبيقات REST، يُرجى الرجوع إلى واجهة برمجة التطبيقات للدليل: حسابات المستخدمين للحصول على معلومات حول تعيين مستخدمي الخرائط ومستندات Cloud Identity للحصول على معلومات عن مجموعات الربط.

إنشاء موصِّل هوية باستخدام حزمة SDK لموصِّل الهوية

ينفِّذ موصِّل الهوية النموذجي المهام التالية:

  1. اضبط الموصل.
  2. استرجع جميع المستخدمين من نظام هوية مؤسستك وأرسلهم إلى Google لمزامنتهم مع هويات Google.
  3. استرجع جميع المجموعات من نظام هوية مؤسستك وأرسلها إلى Google لمزامنتها مع هويات Google.

إعداد التبعيات

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

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-identity-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

 compile group: 'com.google.enterprise.cloudsearch',
         name: 'google-cloudsearch-identity-connector-sdk',
         version: 'v1-0.0.3'

إنشاء إعدادات الموصل

يحتوي كل موصل على ملف تهيئة يحتوي على المعلمات التي يستخدمها الموصل، مثل رقم تعريف المستودع. يتم تعريف المَعلمات على أنّها أزواج من القيم الأساسية، مثل api.sourceId=1234567890abcdef.

تحتوي حزمة تطوير البرامج (SDK) لخدمة Google Cloud Search على العديد من مَعلمات الإعداد التي توفّرها Google وتستخدمها جميع الموصِّلات. يجب الإفصاح عن المعلَمات التالية التي توفّرها Google في ملف الإعداد:

  • بالنسبة إلى موصِّل المحتوى، يجب تعريف api.sourceId وapi.serviceAccountPrivateKeyFile لأنّ هاتَين المعلمتَين تحدّدان موقع المستودع والمفتاح الخاص المطلوب للوصول إلى المستودع.
  • بالنسبة إلى موصِّل الهوية، يجب تعريف api.identitySourceId لأنّ هذه المَعلمة تحدِّد موقع مصدر هويتك الخارجي. في حال مزامنة المستخدمين، عليك أيضًا تصنيف api.customerId كمعرّف فريد لحساب Google Workspace الخاص بمؤسستك.

إذا لم تكن تريد إلغاء القيم التلقائية للمعلَمات الأخرى التي توفّرها Google، لن تحتاج إلى توضيحها في ملف الإعداد. لمزيد من المعلومات عن مَعلمات الإعداد التي توفّرها Google، مثل كيفية إنشاء معرّفات ومفاتيح معيّنة، يمكنك الرجوع إلى مَعلمات الإعداد التي توفّرها Google.

يمكنك أيضًا تحديد المعلمات الخاصة بمستودعك لاستخدامها في ملف الضبط.

تمرير ملف الإعداد إلى الموصل

اضبط خاصية النظام config لتمرير ملف الإعداد إلى الموصل. يمكنك ضبط الخاصية باستخدام الوسيطة -D عند بدء تشغيل الموصل. على سبيل المثال، يبدأ الأمر التالي تشغيل الموصل باستخدام ملف الإعداد MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

في حال عدم توفّر هذه الوسيطة، تحاول حزمة SDK الوصول إلى ملف إعداد تلقائي يُسمى connector-config.properties.

إنشاء موصِّل مزامنة كامل للهوية باستخدام فئة نموذج

تحتوي حزمة تطوير البرامج (SDK) لموصِّل الهوية على فئة نموذج FullSyncIdentityConnector يمكنك استخدامها لمزامنة جميع المستخدمين والمجموعات من مستودع الهوية مع هويات Google. يوضّح هذا القسم كيفية استخدام نموذج FullSyncIdentityConnector لإجراء مزامنة كاملة بين المستخدمين والمجموعات من مستودع هوية غير تابع لشركة Google.

يشير هذا القسم من المستندات إلى مقتطفات رموز من نموذج IdentityConnecorSample.java. يقرأ هذا النموذج هويات المستخدمين والمجموعات من ملفي CSV ويزامنها مع هويات Google.

تنفيذ نقطة دخول الموصل

نقطة الدخول إلى الموصّل هي طريقة main(). تتمثل المهمة الأساسية لهذه الطريقة في إنشاء مثيل للفئة Application واستدعاء طريقة start() الخاصة بها لتشغيل الموصل.

قبل طلب application.start()، استخدِم الفئة IdentityApplication.Builder لإنشاء مثيل لنموذج FullSyncIdentityConnector. تقبل FullSyncIdentityConnector كائن Repository الذي ستنفِّذ طرقه. يعرِض مقتطف الرمز التالي كيفية تنفيذ طريقة main():

IdentityConnectorSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * sync connector. In the full sync case, the repository is responsible
 * for providing a snapshot of the complete identity mappings and
 * group rosters. This is then reconciled against the current set
 * of mappings and groups in Cloud Directory.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new CsvRepository();
  IdentityConnector connector = new FullSyncIdentityConnector(repository);
  IdentityApplication application = new IdentityApplication.Builder(connector, args).build();
  application.start();
}

وراء الكواليس، تستدعي حزمة SDK الطريقة initConfig() بعد استدعاءات طريقة main() للموصل Application.build. تؤدي الطريقة initConfig() المهام التالية:

  1. يتم استدعاء الطريقة Configuation.isInitialized() للتأكد من عدم تهيئة Configuration.
  2. تعمل هذه السياسة على إعداد كائن Configuration باستخدام أزواج المفتاح/القيمة التي توفّرها Google. يتم تخزين كل زوج مفتاح/قيمة في كائن ConfigValue داخل كائن Configuration.

تنفيذ واجهة Repository

الغرض الوحيد من الكائن Repository هو إجراء مزامنة هويات المستودع مع هويات Google. عند استخدام نموذج، ما عليك سوى إلغاء طُرق معيّنة ضمن واجهة Repository لإنشاء موصِّل هوية. بالنسبة إلى FullTraversalConnector، من المحتمل أن تلغي الطرق التالية:

  • الطريقة init(). لإجراء أي إعداد لمستودع هويات وإعداده، عليك إلغاء طريقة `init().

  • الطريقة listUsers(). لمزامنة جميع المستخدمين في مستودع الهوية مع مستخدمي Google، يمكنك إلغاء طريقة listUsers().

  • الطريقة listGroups(). لمزامنة جميع المجموعات في مستودع الهوية مع "مجموعات Google"، يمكنك إلغاء طريقة listGroups().

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

الحصول على معلَمات ضبط مخصّصة

كجزء من معالجة إعدادات الموصل، عليك الحصول على أي معلَمات مخصّصة من الكائن Configuration. يتم تنفيذ هذه المهمة عادةً بطريقة Repository init() للفئة.

تتضمن الفئة Configuration عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. وتُرجع كل طريقة كائن ConfigValue. ستستخدم بعد ذلك طريقة get() للكائن ConfigValue لاسترداد القيمة الفعلية. يعرض المقتطف التالي كيفية استرداد القيمة userMappingCsvPath وgroupMappingCsvPath من كائن Configuration:

IdentityConnectorSample.java
/**
 * Initializes the repository once the SDK is initialized.
 *
 * @param context Injected context, contains convenienve methods
 *                for building users & groups
 * @throws IOException if unable to initialize.
 */
@Override
public void init(RepositoryContext context) throws IOException {
  log.info("Initializing repository");
  this.context = context;
  userMappingCsvPath = Configuration.getString(
      "sample.usersFile", "users.csv").get().trim();
  groupMappingCsvPath = Configuration.getString(
      "sample.groupsFile", "groups.csv").get().trim();
}

للحصول على معلَمة تحتوي على عدة قيم وتحليلها، استخدِم أحد المحللين اللغويين للفئة Configuration لتحليل البيانات في أجزاء منفصلة. يستخدم المقتطف التالي، من موصل البرنامج التعليمي، طريقة getMultiValue للحصول على قائمة بأسماء مستودعات جيت هب:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

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

تجاهُل قيمة listUsers() لاسترداد عملية الربط لجميع المستخدمين من مستودع الهوية. تقبل الطريقة listUsers() نقطة مرجعية تمثل الهوية الأخيرة المطلوب مزامنتها. يمكن استخدام النقطة المرجعية لاستئناف المزامنة في حال مقاطعة العملية. لكل مستخدم في المستودع، عليك تنفيذ الخطوات التالية باستخدام طريقة listUsers():

  1. احصل على عملية ربط تتكون من هوية Google والهوية الخارجية المرتبطة بها.
  2. اجمع الزوج في مكرِّر يتم عرضه من خلال الطريقة listUsers().

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

يوضح مقتطف الرمز التالي كيفية استرداد تعيينات الهوية المخزنة في ملف CSV:

IdentityConnectorSample.java
/**
 * Retrieves all user identity mappings for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the mappings. This is reconciled against the current mappings
 * in Cloud Directory. All identity mappings returned here are
 * set in Cloud Directory. Any previously mapped users that are omitted
 * are unmapped.
 *
 * The connector does not create new users. All users are assumed to
 * exist in Cloud Directory.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of user identity mappings
 * @throws IOException if unable to read user identity mappings
 */
@Override
public CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint)
    throws IOException {
  List<IdentityUser> users = new ArrayList<>();
  try (Reader in = new FileReader(userMappingCsvPath)) {
    // Read user mappings from CSV file
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "primary_email", "external_id"
      String primaryEmailAddress = record.get(0);
      String externalId = record.get(1);
      if (primaryEmailAddress.isEmpty() || externalId.isEmpty()) {
        // Skip any malformed mappings
        continue;
      }
      log.info(() -> String.format("Adding user %s/%s",
          primaryEmailAddress, externalId));

      // Add the identity mapping
      IdentityUser user = context.buildIdentityUser(
          primaryEmailAddress, externalId);
      users.add(user);
    }
  }
  // ...
}

تجميع عملية ربط لمستخدم في مكرّر

تعرض الطريقة listUsers() عنصر Iterator، تحديدًا CheckpointCloseableIterable من عناصر IdentityUser. يمكنك استخدام الفئة CheckpointClosableIterableImpl.Builder لإنشاء مُكرّر وإرجاعه. يوضح مقتطف الرمز التالي كيفية تجميع كل تعيين في قائمة وإنشاء المكرر من تلك القائمة:

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityUser> iterator =
  new CheckpointCloseableIterableImpl.Builder<IdentityUser>(users)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

الحصول على مجموعة

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

  1. الحصول على المجموعة وأعضائها.
  2. عليك تجميع كل مجموعة وأعضاء في تكرار يعرضه الإجراء listGroups().

الحصول على هوية المجموعة

يوضح مقتطف الرمز التالي كيفية استرداد المجموعات والأعضاء المخزنين في ملف CSV:

IdentityConnectorSample.java
/**
 * Retrieves all group rosters for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the rosters. This is reconciled against the current rosters
 * in Cloud Directory. All groups and members  returned here are
 * set in Cloud Directory. Any previously created groups or members
 * that are omitted are removed.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of group rosters
 * @throws IOException if unable to read groups
 */    @Override
public CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint)
    throws IOException {
  List<IdentityGroup> groups = new ArrayList<>();
  try (Reader in = new FileReader(groupMappingCsvPath)) {
    // Read group rosters from CSV
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "group_id", "member"[, ..., "memberN"]
      String groupName = record.get(0);
      log.info(() -> String.format("Adding group %s", groupName));
      // Parse the remaining columns as group memberships
      Supplier<Set<Membership>> members = new MembershipsSupplier(record);
      IdentityGroup group = context.buildIdentityGroup(groupName, members);
      groups.add(group);
    }
  }
  // ...

}

تجميع المجموعة والأعضاء في تكرار

تعرض الطريقة listGroups() عنصر Iterator، تحديدًا CheckpointCloseableIterable من عناصر IdentityGroup. يمكنك استخدام الفئة CheckpointClosableIterableImpl.Builder لإنشاء مُكرّر وإرجاعه. يوضح مقتطف الرمز التالي كيفية تجميع كل مجموعة وأعضاء في قائمة وإنشاء المكرر من تلك القائمة:

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityGroup> iterator =
   new CheckpointCloseableIterableImpl.Builder<IdentityGroup>(groups)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

الخطوات التالية

في ما يلي بعض الخطوات التي يمكنك اتّخاذها:

  • (اختياري) نفِّذ طريقة closed() لتحرير أي موارد قبل إيقاف التشغيل.
  • (اختياري) أنشئ موصِّل محتوى باستخدام حزمة تطوير البرامج (SDK) لموصِّل المحتوى.