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

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

تقدم Google الخيارات التالية لتطوير موصلات الهوية:

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

• واجهة برمجة تطبيقات REST منخفضة المستوى وواجهة برمجة تطبيقات REST. هذه الخيارات مخصصة لمطوّري البرامج الذين قد لا يتولون برمجة في جافا أو التي تستوعب قاعدة شفراتها بشكل أفضل واجهة برمجة تطبيقات REST أو مكتبة. لإنشاء موصِّل هويات باستخدام واجهة برمجة تطبيقات REST، يُرجى الرجوع إلى واجهة برمجة تطبيقات الدليل: حسابات المستخدمين للحصول على معلومات حول ربط المستخدمين ومستندات 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.

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

تحتوي حزمة 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 للصف 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 لموصل المحتوى.