From f305af3d8bdcb98fa9ff04f0aa1014afae012296 Mon Sep 17 00:00:00 2001 From: PhakornKiong Date: Wed, 6 Oct 2021 02:01:49 +0800 Subject: [PATCH 1/2] update document for msgraph client Signed-off-by: PhakornKiong --- .../api-report.md | 13 +--- .../src/microsoftGraph/client.ts | 76 +++++++++++++++++++ 2 files changed, 79 insertions(+), 10 deletions(-) diff --git a/plugins/catalog-backend-module-msgraph/api-report.md b/plugins/catalog-backend-module-msgraph/api-report.md index 59404ad9dd..d290fcf9b6 100644 --- a/plugins/catalog-backend-module-msgraph/api-report.md +++ b/plugins/catalog-backend-module-msgraph/api-report.md @@ -66,36 +66,29 @@ export class MicrosoftGraphClient { constructor(baseUrl: string, pca: msal.ConfidentialClientApplication); static create(config: MicrosoftGraphProviderConfig): MicrosoftGraphClient; // Warning: (ae-forgotten-export) The symbol "GroupMember" needs to be exported by the entry point index.d.ts - // - // (undocumented) getGroupMembers(groupId: string): AsyncIterable; // (undocumented) getGroupPhoto(groupId: string, sizeId?: string): Promise; - // (undocumented) getGroupPhotoWithSizeLimit( groupId: string, maxSize: number, ): Promise; - // (undocumented) + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery" getGroups(query?: ODataQuery): AsyncIterable; - // (undocumented) getOrganization(tenantId: string): Promise; // (undocumented) getUserPhoto(userId: string, sizeId?: string): Promise; - // (undocumented) getUserPhotoWithSizeLimit( userId: string, maxSize: number, ): Promise; - // (undocumented) getUserProfile(userId: string): Promise; - // (undocumented) + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery" getUsers(query?: ODataQuery): AsyncIterable; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery" requestApi(path: string, query?: ODataQuery): Promise; // Warning: (ae-forgotten-export) The symbol "ODataQuery" needs to be exported by the entry point index.d.ts - // - // (undocumented) + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery" requestCollection(path: string, query?: ODataQuery): AsyncIterable; requestRaw(url: string): Promise; } diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts index 0c8f5e7dc8..83b4371c0d 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts @@ -84,6 +84,15 @@ export class MicrosoftGraphClient { private readonly pca: msal.ConfidentialClientApplication, ) {} + /** + * Get a collection of resource from Graph API and + * return an `AsyncIterable` of that resource + * + * @public + * @param path - Resource in Microsoft Graph + * @param query - OData Query {@link ODataQuery} + * + */ async *requestCollection( path: string, query?: ODataQuery, @@ -96,6 +105,8 @@ export class MicrosoftGraphClient { } const result = await response.json(); + + // Graph API return array of collections const elements: T[] = result.value; yield* elements; @@ -155,6 +166,14 @@ export class MicrosoftGraphClient { }); } + /** + * Get {@link https://docs.microsoft.com/en-us/graph/api/resources/user | User} + * from Graph API + * + * @public + * @param userId - The unique identifier for the `User` resource + * + */ async getUserProfile(userId: string): Promise { const response = await this.requestApi(`users/${userId}`); @@ -165,6 +184,14 @@ export class MicrosoftGraphClient { return await response.json(); } + /** + * Get {@link https://docs.microsoft.com/en-us/graph/api/resources/profilephoto | profilePhoto} + * of `User` from Graph API with size limit + * + * @param userId - The unique identifier for the `User` resource + * @param maxSize - Maximum pixel height of the photo + * + */ async getUserPhotoWithSizeLimit( userId: string, maxSize: number, @@ -179,10 +206,27 @@ export class MicrosoftGraphClient { return await this.getPhoto('users', userId, sizeId); } + /** + * Get a collection of + * {@link https://docs.microsoft.com/en-us/graph/api/resources/user | User} + * from Graph API and return as `AsyncIterable` + * + * @public + * @param query - OData Query {@link ODataQuery} + * + */ async *getUsers(query?: ODataQuery): AsyncIterable { yield* this.requestCollection(`users`, query); } + /** + * Get {@link https://docs.microsoft.com/en-us/graph/api/resources/profilephoto | profilePhoto} + * of `Group` from Graph API with size limit + * + * @param groupId - The unique identifier for the `Group` resource + * @param maxSize - Maximum pixel height of the photo + * + */ async getGroupPhotoWithSizeLimit( groupId: string, maxSize: number, @@ -197,14 +241,37 @@ export class MicrosoftGraphClient { return await this.getPhoto('groups', groupId, sizeId); } + /** + * Get a collection of + * {@link https://docs.microsoft.com/en-us/graph/api/resources/group | Group} + * from Graph API and return as `AsyncIterable` + * @public + * @param query - OData Query {@link ODataQuery} + * + */ async *getGroups(query?: ODataQuery): AsyncIterable { yield* this.requestCollection(`groups`, query); } + /** + * Get a collection of + * {@link https://docs.microsoft.com/en-us/graph/api/resources/user | User} + * belonging to a `Group` from Graph API and return as `AsyncIterable` + * @public + * @param groupId - The unique identifier for the `Group` resource + * + */ async *getGroupMembers(groupId: string): AsyncIterable { yield* this.requestCollection(`groups/${groupId}/members`); } + /** + * Get {@link https://docs.microsoft.com/en-us/graph/api/resources/organization | Organization} + * from Graph API + * @public + * @param tenantId - The unique identifier for the `Organization` resource + * + */ async getOrganization( tenantId: string, ): Promise { @@ -217,6 +284,15 @@ export class MicrosoftGraphClient { return await response.json(); } + /** + * Get {@link https://docs.microsoft.com/en-us/graph/api/resources/profilephoto | profilePhoto} + * from Graph API + * + * @param entityName - type of parent resource, either `User` or `Group` + * @param id - The unique identifier for the {@link entityName | entityName} resource + * @param maxSize - Maximum pixel height of the photo + * + */ private async getPhotoWithSizeLimit( entityName: string, id: string, From 95869261ed262f38a22cad464ae9b71978acb260 Mon Sep 17 00:00:00 2001 From: Ben Lambert Date: Wed, 6 Oct 2021 10:55:30 +0200 Subject: [PATCH 2/2] Added changeset Signed-off-by: Ben Lambert --- .changeset/good-ghosts-kiss.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/good-ghosts-kiss.md diff --git a/.changeset/good-ghosts-kiss.md b/.changeset/good-ghosts-kiss.md new file mode 100644 index 0000000000..0e6122fbc9 --- /dev/null +++ b/.changeset/good-ghosts-kiss.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend-module-msgraph': patch +--- + +Adding some documentation for the `msgraph` client