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

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

توفّر Google الخيارات التالية لتطوير أدوات ربط الهوية:

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

إنشاء موصّل هوية باستخدام Identity Connector SDK

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

تضبط هذه السمة الموصّل.
يستردّ المستخدمين من نظام تحديد الهوية ويرسلهم إلى Google.
يستردّ المجموعات من نظام تحديد الهوية ويرسلها إلى 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

عرض على GitHub

/**
 * 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():

يضمن عدم تهيئة Configuration من قبل.
تتم تهيئة العنصر Configuration باستخدام أزواج المفتاح/القيمة التي توفّرها Google.

تنفيذ واجهة Repository

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

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

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

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

IdentityConnectorSample.java

عرض على GitHub

/**
 * 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

عرض على GitHub

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

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

استبدِل listUsers() لاسترداد عمليات ربط المستخدمين. تقبل هذه الطريقة نقطة توقّف مؤقت لاستئناف المزامنة في حال انقطاعها. لكل مستخدم:

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

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

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

IdentityConnectorSample.java

عرض على GitHub

/**
 * 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

عرض على GitHub

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

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

استبدِل listGroups() لاسترداد المجموعات وأعضائها. تقبل هذه الطريقة نقطة توقّف. لكل مجموعة:

الحصول على المجموعة وأعضائها
يتم تجميعها في المكرّر الذي تعرضه الدالة listGroups().

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

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

IdentityConnectorSample.java

عرض على GitHub

/**
 * 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

عرض على GitHub

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

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

(اختياري) نفِّذ close() لتحرير الموارد.
(اختياري) إنشاء أداة ربط محتوى

إنشاء موصِّل هوية تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إنشاء موصّل هوية باستخدام Identity Connector SDK

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

Maven

Gradle

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

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

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

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

تنفيذ واجهة Repository

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

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

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

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

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

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

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

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

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