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

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

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

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

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

إنشاء موصّل هوية باستخدام Identity Connector 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() لمزامنة كل المجموعات في مستودع الهوية مع &quot;مجموعات Google&quot;، عليك إلغاء طريقة 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 للحصول على قائمة بأسماء مستودعات GitHub:

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();

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

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