search

sreeise / graph-rs-sdk

Microsoft Graph API Client And Identity Platform Client in Rust
MIT License
114 stars 30 forks source link

Generate Workbooks APIs #447

Closed sreeise closed 10 months ago

sreeise commented 1 year ago

This ticket has been reopened because there is a large amount of missing APIs related to workbooks and worksheets.

Code generation needs to be done for Workbook APIs: https://learn.microsoft.com/en-us/graph/api/resources/excel?view=graph-rest-1.0

We are currently missing several APIs for workbooks and worksheets:

Microsoft API reference here: https://learn.microsoft.com/en-us/graph/api/resources/excel?view=graph-rest-1.0

You can print a list of what APIs are in the OpenAPI metadata by cloning the repo and creating a rust file in the examples directory with the following code:

use graph_codegen::openapi::OpenApi;

fn main() {
    let open_api = OpenApi::default();

    open_api.debug_path_contains("workbook");
}

For a walkthrough on generating APIs see: https://github.com/sreeise/graph-rs-sdk/wiki/Codegen-%E2%80%90-Generating-API's

Most of the workbook/worksheet APIs will just need links for the drive items APIs. You can add those links by running the code generation by updating the code here with the following:

ResourceIdentity::DrivesItems => WriteConfiguration::second_level_builder(ResourceIdentity::Drives, resource_identity)
    .trim_path_start("/drives/{drive-id}")
    .imports(vec!["crate::drives::{CreatedByUserApiClient, LastModifiedByUserApiClient, WorkbookApiClient, WorksheetsApiClient, WorksheetsIdApiClient}"])
    .filter_path(vec!["workbook", "getActivitiesByInterval()", "createdByUser", "lastModifiedByUser"])
    .api_client_links(vec![
        ApiClientLinkSettings(Some("DrivesItemsIdApiClient"), vec![
            ApiClientLink::Struct("workbook", "WorkbookApiClient"),
            ApiClientLink::StructId("worksheets", "WorksheetsApiClient"),
            ApiClientLink::Struct("worksheet", "WorksheetsIdApiClient"),
        ])
    ])
    .build()
    .unwrap(),
buhaytza2005 commented 10 months ago

Would it be possible to add an example of how to access a workbook?

I've been sifting through the code and the most progress I have so far is that I realized the .workbook() cannot be accessed from the default drive API :)

If I can just get a bit of guidance and make it work I can probably submit a PR to add some examples to the repo.

Thanks for all your work!

sreeise commented 10 months ago

Would it be possible to add an example of how to access a workbook?

I've been sifting through the code and the most progress I have so far is that I realized the .workbook() cannot be accessed from the default drive API :)

If I can just get a bit of guidance and make it work I can probably submit a PR to add some examples to the repo.

Thanks for all your work!

Hi @buhaytza2005

Sure I can try to help. Looking back through the APIs for workbooks/worksheets I think the sdk is actually missing a large part of the APIs for it. Specifically, the item APIs which would allow you to access a specific workbook. Ones that start with the path /drives/{drive-id}/items/{driveItem-id}/workbook/.

I apologize for that. I will reopen this ticket and update it.

What you should be able to do, if this was in the SDK, is this:

client.drive("drive-id")
        .item("item-id")
        .workbook()

or

client.me()
        .drive()
        .item("item-id")
        .workbook()

where the item-id is the id of the workbook in OneDrive.

buhaytza2005 commented 10 months ago

I tried to make this work - starting with the suggested linking to wrap my head around how it all works but I'm probably missing something.

Here are the steps I followed:

I tried to sites, drive etc to rewrite the files but ended up duplicating some of the methods. The codegen page refers to this as an issue and removing the files the have been generated - would this just be a case of a bit of bash magic an removing files listed in the diff or is there a built-in way of doing this?

Am I just think and not understanding how the code generation works?

Sorry if these questions are silly but I'm really excited about this library and would love to understand the lay of the land. Thanks!

LE: When adding the links manually it seems to work in some basic cases. I have found a couple of bits where the paths don't seem to be correct, like needing workbook here - once I can wrap my head around codegen I can probably troubleshoot/test all methods it as I will be using this for a project:

impl WorksheetsApiClient {
    [..]
    get!(
        doc: "List WorksheetCollection",
        name: list_worksheets,
        path: "/workbook/worksheets"
    );
    [..]
}
sreeise commented 10 months ago

I tried to make this work - starting with the suggested linking to wrap my head around how it all works but I'm probably missing something.

Here are the steps I followed:

* I took the code from the first post and replaced the old arm in `resource_settings.rs`

* Created a `test.rs` file in examples

* Followed the instructions on the Codegen page and added the line below in `test.rs` - I am making an assumption that only this would need to be regenerated?
OpenApi::write(get_write_configuration(ResourceIdentity::DrivesItems));
* Ran the file with `cargo run --example test`

* In the diff I can see the below but I expected to see links for `workbook`, `worksheets` and `worksheet` too.
 impl DrivesItemsApiClient {
+    api_client_link!(last_modified_by_user, LastModifiedByUserApiClient);
+    api_client_link!(created_by_user, CreatedByUserApiClient);
+

Furthermore, nothing was added under DrivesItemsApiClient.

I tried to sites, drive etc to rewrite the files but ended up duplicating some of the methods. The codegen page refers to this as an issue and removing the files the have been generated - would this just be a case of a bit of bash magic an removing files listed in the diff or is there a built-in way of doing this?

Am I just think and not understanding how the code generation works?

Sorry if these questions are silly but I'm really excited about this library and would love to understand the lay of the land. Thanks!

LE: When adding the links manually it seems to work in some basic cases. I have found a couple of bits where the paths don't seem to be correct, like needing workbook here - once I can wrap my head around codegen I can probably troubleshoot/test all methods it as I will be using this for a project:

impl WorksheetsApiClient {
    [..]
    get!(
        doc: "List WorksheetCollection",
        name: list_worksheets,
        path: "/workbook/worksheets"
    );
    [..]
}

Hey, its awesome that you took the time to do that and get involved.

The workbooks APIs are so large that the code generation updates are pretty heavily involved and there are is a lot of work in it. For someone just learning how the code generation works its probably not going to help to start with this. I appreciate you trying it and I apologize I didn't mention this earlier.

I have a branch that I am adding the rest of the workbooks code generation for.

I'll be pushing it up here soon within the next day and i'll link it here so you can see all the changes that needed to be made. This specific API, meaning workbooks, is unusual in how difficult it is to generate the code for. Normally most APIs are much smaller and easier to reason with.

On adding links specifically. those have to be added using ApiClientLinkSettings for the ResourceSettings match here https://github.com/sreeise/graph-rs-sdk/blob/2a70fa165357a6de13c91e2bffb82421e3167299/graph-codegen/src/settings/resource_settings.rs#L38.

I am still trying to move the link generation from ResourceSettings to WriteConfiguration where the rest of the codegen configuration is handled. Just a lot of work that I havn't had time for and its kind of taken a back seat for right now. You can see in that same page there is methods that match ResourceIdentity and return WriteConfiguration and one that returns ResourceSettings. Whats left of ResourceSettings is being slowly transferred to WriteConfiguration. You can think of WriteConfiguration as the codegen configuration for the APIs basically.

sreeise commented 10 months ago

@buhaytza2005 I had to fix a few things so it ended up being a little more in the PR than just code generation. But for the most part thats what this PR is for: https://github.com/sreeise/graph-rs-sdk/pull/457

Feel free to take a look if you want. Its a lot of changes and may not be all that useful but if you go into the src/drives folder you can see all the new generated folders/files for workbooks and worksheets.

buhaytza2005 commented 10 months ago

I'll definitely dig through the changes. I am looking at the bookings API as a simpler one to dip my toes into the code generation - trying to kill 2 birds with one stone as that only seems to have a few entities such as the business, staff and appointments as opposed to the myriad of objects in Workbooks & worksheets.

One more time, thanks for your work!

sreeise commented 10 months ago

I tried to sites, drive etc to rewrite the files but ended up duplicating some of the methods. The codegen page refers to this as an issue and removing the files the have been generated - would this just be a case of a bit of bash magic an removing files listed in the diff or is there a built-in way of doing this?

It depends on where im at in the process, at least for me. A lot of times i'll be generating multiple modules but only one has method names that are duplicated. After adding that to the codgen configuration, i'll open the rust file thats causing the failure, copy the imports and resource_api_client macro calls at the top of the page to my clipboard, then I do Ctrl-A and erase everything in the file and paste my clipboard.

This makes it so the structs for the api client are still generated but all of the duplicated methods are erased so it won't cause it to fail compilation. And then you can just run the codgen again which will overwrite the file with the updated code.

Sometimes I use git to just stash changes or undo changes to files until ive gotten the configuration correct to where it will generate code that won't fail to compile. I typically use some of the features in JetBrains IDEs for Git. It comes in handy when I just need to wipe the current changes in certain files.

In the future, I would like to move the codegen lilbrary to another repository and have it be able to generate code without needing the whole graph-rs-sdk project to compile. But graph-codgen still uses some imports from graph-http and graph-core crates in the same repository so those need to be decoupled first.

sreeise commented 10 months ago

@buhaytza2005 I merged my PR which automatically closed the issue. I'll try to get a new version to crates.io within a couple of days if your wondering about using the crate. If you are using the API for workbooks/worksheets and notice any issues feel free to comment here or reopen or open a new issue. Its a lot of changes so its possible there may be something I missed.

buhaytza2005 commented 10 months ago

That's great! I have pulled the code with a github link and managed to get it up and running.

All seems to be fine except the one part I can't find is:

PATCH /me/drive/items/{id}/workbook/names/{name}/range
PATCH /me/drive/root:/{item-path}:/workbook/names/{name}/range
PATCH /me/drive/items/{id}/workbook/worksheets/{id|name}/range(address='<address>')
PATCH /me/drive/root:/{item-path}:/workbook/worksheets/{id|name}/range(address='<address>')
PATCH /me/drive/items/{id}/workbook/tables/{id|name}/columns/{id|name}/range
PATCH /me/drive/root:/{item-path}:/workbook/tables/{id|name}/columns/{id|name}/range

There seem to be implementations for ranges, cols and rows in tables but not directly in the spreadsheets.

It appears that there should be an extra item Range that would probably hook all this up.

image

Currently, I can just transform the data into a table and update that way and that's probably going to suffice for this current project.

Thanks, Mike

sreeise commented 10 months ago

That's great! I have pulled the code with a github link and managed to get it up and running.

All seems to be fine except the one part I can't find is:

PATCH /me/drive/items/{id}/workbook/names/{name}/range
PATCH /me/drive/root:/{item-path}:/workbook/names/{name}/range
PATCH /me/drive/items/{id}/workbook/worksheets/{id|name}/range(address='<address>')
PATCH /me/drive/root:/{item-path}:/workbook/worksheets/{id|name}/range(address='<address>')
PATCH /me/drive/items/{id}/workbook/tables/{id|name}/columns/{id|name}/range
PATCH /me/drive/root:/{item-path}:/workbook/tables/{id|name}/columns/{id|name}/range

There seem to be implementations for ranges, cols and rows in tables but not directly in the spreadsheets.

It appears that there should be an extra item Range that would probably hook all this up.

image

Currently, I can just transform the data into a table and update that way and that's probably going to suffice for this current project.

Thanks, Mike

There are GET requests for several of these but the OpenAPI metadata doesn't have the PATCH for these listed which is why it didn't get generated. 

    // GET /me/drive/root:/{item-path}:/workbook/tables/{id|name}/columns/{id|name}/range
    let _response = client.me()
        .drive()
        .item("item-id")
        .workbook()
        .table("table-id")
        .column("column-id")
        .range()
        .send()
        .await?;

    // GET /me/drive/root:/{item-path}:/workbook/worksheets/{id|name}/range(address='<address>')
    let _response = client.me()
        .drive()
        .item("item-id")
        .workbook()
        .worksheet("worksheet-id")
        .get_range_object_by_address()
        .send()
        .await?;

They can be added manually to manual_request.rs by adding an impl block of whichever API client it needs to go under. For instance, adding the PATCH for range object by address to worksheet you would do an impl block for worksheet in manual_request.rs:

impl WorksheetsIdApiClient {
    patch!(
        doc: "Invoke function range",
        name: update_range_object_by_address,
        path: "/worksheets/{{RID}}/range(address='{{id}}')",
        body: true,
        params: address
    );
}

Theres really no telling when Microsoft will add these to the OpenAPI metadata but they update it all the time I know that. Feel free to open a ticket for those and please consider contributing a PR for these changes if you have the time.

buhaytza2005 commented 10 months ago

Sure thing. Would these need their own manual_request in their folders or just add all to the file in the drives folder?

sreeise commented 10 months ago

Sure thing. Would these need their own manual_request in their folders or just add all to the file in the drives folder?

You can just put it in the one that is in the drives folder. If it doesn't compile because of where the file is located then yeah I guess it would have to be in the folders where the mod files are at. But hopefully this just works without having to do that.