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

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

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

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

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

إنشاء موصِّل هويات باستخدام حزمة تطوير البرامج (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.

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

تحتوي حزمة تطوير البرامج لموصّل الهوية على فئة نموذج 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 الصف 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 للحصول على قائمة بأسماء مستودعات جيت هب:

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

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

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

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

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

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