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

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

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

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

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

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

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

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

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

يجب تضمين ملحقَين معيّنين في ملف الإنشاء لاستخدام حزمة SDK. انقر على علامة تبويب أدناه لعرض التبعيات لبيئة الإصدار:

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

 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) الوصول إلى ملف إعدادات default بعنوان connector-config.properties.

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

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

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

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

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

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

/**
 * 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 class's init().

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

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

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

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

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

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

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

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

/**
 * 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 لإنشاء مكرّر وإرجاعه. يوضّح المقتطف التالي من الرمز البرمجي كيفية تجميع كل تعيين في قائمة وإنشاء الموسّع من تلك القائمة:

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

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

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

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

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

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

/**
 * 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 لإنشاء مكرّر وإرجاعه. يوضّح المقتطف التالي من الرمز البرمجي كيفية تجميع كل مجموعة وأعضاء في قائمة وإنشاء الموسّع من تلك القائمة:

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

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

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

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