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

لا يتعرّف Google Cloud Search تلقائيًا إلا على هويات Google في "دليل Google Cloud". استخدِم موصّلات الهوية لمزامنة هويات المؤسسة مع هويات Google التي يستخدمها Cloud Search.

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

إنشاء موصّل هوية باستخدام حزمة تطوير البرامج (SDK) لموصّل الهوية

ينفّذ موصّل الهوية العادي المهام التالية:

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

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

يجب تضمين هذه التبعيات في ملف الإصدار.

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 لجميع الموصّلات. يجب الإعلان عن ما يلي في ملف الإعدادات:

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

يجب الإعلان عن المَعلمات الأخرى المقدَّمة من Google فقط لإلغاء قيمها التلقائية. لمعرفة التفاصيل حول إنشاء أرقام التعريف والمفاتيح، يُرجى الاطّلاع على مقالة المَعلمات المقدَّمة من Google.

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

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

يمكنك ضبط خاصية النظام config لتمرير ملف الإعدادات. استخدِم الوسيطة -D عند بدء الموصّل. على سبيل المثال:

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

إذا لم يتم تضمين هذه الوسيطة، تحاول حزمة تطوير البرامج (SDK) استخدام ملف باسم connector-config.properties في الدليل المحلي.

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

تتضمّن حزمة تطوير البرامج (SDK) نموذج FullSyncIdentityConnector لمزامنة جميع المستخدمين والمجموعات من المستودع. يوضّح هذا القسم كيفية استخدامه.

يشير هذا القسم إلى الرمز من نموذج IdentityConnectorSample.java الذي يقرأ الهويات من ملفات CSV.

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

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

قبل استدعاء application.start()، استخدِم IdentityApplication.Builder لإنشاء مثيل لنموذج FullSyncIdentityConnector.

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. التأكّد من عدم تهيئة Configuration من قبل
  2. تهيئة عنصر Configuration باستخدام أزواج المفتاح والقيمة المقدَّمة من Google

تنفيذ واجهة Repository

يزامن عنصر Repository هويات المستودع مع هويات Google. عند استخدام نموذج، ما عليك سوى إلغاء طرق معيّنة. بالنسبة إلى FullSyncIdentityConnector، يجب إلغاء الطرق التالية:

  • init(): للإعداد والتهيئة
  • listUsers(): لمزامنة جميع المستخدمين
  • listGroups(): لمزامنة جميع المجموعات
  • (اختياري) close(): للتنظيف أثناء الإيقاف

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

يمكنك استرداد المَعلمات المخصّصة من عنصر Configuration، عادةً في طريقة init(). يوضّح المقتطف التالي كيفية استرداد مسارات CSV:

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 للحصول على قائمة بأسماء مستودعات GitHub:

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

الحصول على عملية الربط لجميع المستخدمين

يمكنك إلغاء 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() عنصر CheckpointCloseableIterable من IdentityUser عناصر.

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

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

يمكنك إلغاء 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() عنصر CheckpointCloseableIterable من IdentityGroup عناصر.

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

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