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

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

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

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

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

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

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

يؤدي موصل الهوية النموذجي المهام التالية:

  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(). لمزامنة كل المجموعات في مستودع الهوية مع مجموعات Google، ألغ طريقة listGroups().

  • (اختياري) الطريقة close(). وإذا كنت بحاجة إلى إزالة البرامج غير المرغوب فيها من المستودع، يمكنك إلغاء الطريقة close(). يتم استدعاء هذه الطريقة مرة واحدة أثناء إيقاف الموصل.

الحصول على معلمات ضبط مخصصة

كجزء من معالجة ضبط الموصِّل، ستحتاج إلى الحصول على أي معلّمات مخصّصة من الكائن Configuration. يتم تنفيذ هذه المهمة عادةً بطريقة Repository class's init().

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

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

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

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