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

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

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

• حزمة تطوير البرامج لموصّل الهوية. هذا الخيار مخصص للمطورين الذين يبرمجون بلغة برمجة Java. تُعد حزمة تطوير البرامج (SDK) لموصِّل الهوية برنامج تضمين حول واجهة برمجة تطبيقات REST تسمح لك بإنشاء الموصلات بسرعة. لإنشاء موصِّل هوية باستخدام حزمة تطوير البرامج (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) الوصول إلى ملف إعداد تلقائي باسم connector-config.properties.

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

تحتوي حزمة تطوير البرامج لموصّل الهوية على فئة نماذج 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. يتم تنفيذ هذه المهمة عادةً بطريقة init() الخاصة بفئة Repository.

تتضمن الفئة Configuration عدة طرق للحصول على أنواع بيانات مختلفة من الإعدادات. تؤدي كل طريقة إلى عرض كائن ConfigValue. يمكنك بعد ذلك استخدام طريقة get() الخاصة بكائن ConfigValue لاسترداد القيمة الفعلية. يوضّح المقتطف التالي كيفية استرداد قيمة 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();

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

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

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