Google Drive Sdk Question Time

CLAUDIO: Hi everyone, and welcome back to the Google Drive SDK question time. My name is Claudio and this is Ali. ALI: Hi everyone. CLAUDIO: We are two engineers in the Google Drive developer relations team. Today we're going to show you a tool we have developed called the OAuth 2.0 Playground. We think this tool will make it easy for developers and users in general to test the API. So it can be used for many APIs but today we're going to use it for the Drive API. Ali, can you tell us a bit more about the OAuth Playground? ALI: So we use OAuth 2.0 as our best authorization mechanism for using all our APIs. It's not only just us, it's becoming an industry standard way of authorization. Now we developed this tool called the OAuth 2.0 Playground that allows you to debug and test and experiment with the OAuth flow. If you've ever used OAuth, you know it's not entirely simple. It's quite straightforward, but there are a few steps. And what this tool does is it allows you to go through the steps, it shows you how they work, it shows you the full debugging output, and then it allows you to make requests with APIs using the authorization credentials that you've got. CLAUDIO: Let's see how we can use it with a set of scenarios. So I think we can start from the Google Drive UI. And the OAuth 2.0 Playground is integrated with the UI, so we can start from there and see how we can reach to the application. ALI: OK. So this is the Google Drive user interface. I'm sure you're all familiar with it. But one thing we've allowed with the OAuth Playground is we allow you to open files from the drive user interface in the OAuth Playground. OK. So here's a list of files. What I'm going to do is I'm going to right-click on this. Because I've got the OAuth 2.0 Playground installed and a few other drive apps, I just click Open with the OAuth 2.0 Playground. And what happens is I get an authorization request and it goes through the first step of OAuth. So you can see here, if you're familiar with OAuth 2.0, you know that once authorization has happened, a redirect occurs to the server with the code and the information I need. The code is here in this box and this allows me to perform the next step of the OAuth 2.0 dance, which is to exchange the code for a token. And if you see, I've exchanged the code here, just go back there, and I've got this access token. Quickly copy that down, because you'll be able to use it to access my data. It's OK, it's just a test account so there's nothing really you can do in there. Once you've done that, you can then make API requests. Now, because I opened this file directly in the OAuth Playground, it's already preloaded a request for me. And so what do I do? I make that API request and I get a response. Let's just look at that quickly. So what was the request we made? Well, it was a Get here to that URL using the code that-- the access token that we just obtained, which is there. And we get a response. It's a 200. Fantastic. The usual kind of headers, content length. And then the JSON response. And if you've seen any of our documentation or if you used our APIs, you know this is fairly standard. There are few fields, interesting ones. Download URL we'll have a look at later. The title, which is test image, which you can see corresponds to the title in the drive user interface. And the MIME type of the file, which is an image.png. Makes sense. We have some labels here that refer to Boolean attributes on the file itself, whether it's starred, whether it's hidden, whether it's trashed. That kind of thing. So this allows you immediately to get into a situation where you are debugging driver API calls directly from the drive user interface. CLAUDIO: That's perfect and that works perfectly and it's super easy when you start from the drive UI. So you just right-click on a file and you open it from the OAuth Playground. But what if you want to start directly from the OAuth Playground? ALI: OK. So this big X here resets all the settings. That's great. So I've reset all of that. Now, when you do OAuth 2.0-- and this was preselected for us when we came from the drive user interface, but you have to pick a scope or multiple scopes. And you see all our APIs are listed here, but the one we're interested in is the Google Drive scope. We click Authorize and, of course, we're going to get through to the OAuth authorization page. This is what a user would see to say, do you give access to this application or not? And you can see the application here is the OAuth Playground. So we allow access and we get redirected back here with the code which we exchange as before. CLAUDIO: So starting from here, it's exactly the same flow as before. ALI: Exactly. It's slightly different. You might have noticed that here, we have a refresh token, and previously we didn't have a refresh token. This just means that we can have offline access, ie, when our access token expires, we can refresh it and get a new access token. So that's the only difference, but apart from that, it's exactly the same. Now, what we can do here is we can enter our custom request. That was preselected for us before. But what we find is this really useful button called Find Available Request URIs. And that gives an ordered list of all the endpoints for this API with the various parameters that you need. So what was the first thing you wanted to do, Claudio? CLAUDIO: I would say that the first thing is to list all the files the OAuth Playground is allowed to open. So we look for a list files method and that should be it, right? ALI: Yeah. That's just there. So you can click on the URI and it preloads it in there. That's all we're doing. And it will show you that you just need to make a Get to this request, send the request, and here's our response. Do you want talk about this a bit, Claudio? CLAUDIO: Sure. So the response is now field feed containing a number of entries. For each entry, as the one you showed before, there is a set of attributes we set. Each of them has a number of links to download the document, export a document in different formats, and another set of metadata, like the title, the MIME type. This case the one we're looking at right now is a text file, a plain text file. And the same levels as before. So if this item has being starred, if it's in trash, something else like the extension-- a very useful MD5 checksum, which is a checksum for the content of the file. So you can use that field to know if the content has changed and many other details, including the name of the owner, the size of this file on your storage, who is the user that last modified it, and what are your permissions on this file? ALI: So this is interesting because as you might may know in Google Drive, you have two kinds of files. One are binary files that we store the content, and the other type are Google Docs files. Now, some of these attributes are only available for binary files, for example, the original file name, the amount of quota the file is using. Google Docs files and Google Docs spreadsheets, presentations, drawings-- all of these occupy zero of your quota. That's just worth saying. So you get two slightly different types, and these are only present-- and, of course, the MD5 checksum is only present on these kind of files as well. CLAUDIO: Can we download a file from here? ALI: So it's a text file. So conveniently with the OAuth Playground, you can't download binary files, unfortunately. That's a feature that we should probably add. But you can download text files because it's just text. So one thing we've got in here is the download URL. So you can just click on this download URL and you see it's preloaded now in the Request URI. And if I click on Send the Request, before I do it, it will make an authorized Get request to this, which it needs to be authorized. Of course, we don't want to share this file with just anyone, even if they know what the link is. So we make that request and fingers crossed, it should work. I think it's going to. You get a 200 with some interesting information in the headers, actually. For example, the content disposition which allows your application to create the correctly named file, in this case hello.txt. And we go down to the bottom and we see the content of the file, Hello Drive SDK users. CLAUDIO: Well, how cheesy it that? ALI: Well, I didn't even prepare it for this. I'm joking. I did prepare it for this. CLAUDIO: I believed you. ALI: So that's how you use the Download URL and you can do that. I can't show you with any binary files because, obviously, binary data would not be rendered properly in this browser. So that's why we're using a text file here. CLAUDIO: What about exporting documents in different formats? We're not going to do it now, but how can you do that? ALI: OK. So just to show you that, let's just pick a file. Now for exporting, we're talking about Google Docs types really, aren't we? So which one would you like? One of these Google Docs files, I guess. Probably presentation? CLAUDIO: It's probably presentation. ALI: Let's use that one. So if I just open that with-- this saves me listing a file, finding the ID, performing a Get on it. It just saves all of that information. So let's get the file and we see here in the file for Google Docs types, we will have a export link. CLAUDIO: We sent a request to Version 1 of the API. ALI: Rather than Version 2 of the API. I can just about see that. Let's see. Will that work? OK. So now we've got that and we see among all these links, we will have a link-- a set of links called the export links. Now, these are great because although you could probably try and construct that URL manually, we strongly advise against you doing that. But for each type you can export, in this case, txt, pdf,-- CLAUDIO: OpenOffice-- ALI: OpenOffice presentations. It offers you a different download URL that you can use. CLAUDIO: Well actually, that is not OpenOffice presentation. I lied. That is pptx. So it's a new format for Microsoft PowerPoint presentation. ALI: Interesting. CLAUDIO: So you just take that link, download the file from that link. And then you get the file in exported format. ALI: Exactly. And we can't show you because, of course, they are binary formats. CLAUDIO: And how can you know what the available export formats are? ALI: OK. So this really depends on the type of file, but we do list this information in what we call-- and let's start again. We call the About feed. OK. While I'm doing this, do you just want to explain a bit about the About feed. CLAUDIO: So in the Drive API, we have many feeds that you can get. The one we have used so far is the File Scope, which is the feed you have to use to list all your files, to search for files, to download files, and so on. But there are others, including the Permissions feeds, which returns permissions for a file or a folder, or the Changes feed, which lists old changes that happen to your document list. But there is also another feed called the About feed. The About feed includes-- it's a read-only feed that includes a set of metadata. So you can get the list of available export formats for all of the source documents we know, a list of reports from us for all the documents we can import, and other information we're going to show you when we get that feed. ALI: So as you can see, I've just clicked on this link here, About. And the URL is easy. It's just a Get to our API with the version and then About. And I click Get. And of course, I'm going to get a 200 response back, and with loads of information. So just to shoot quickly to what Claudio was talking about with the export formats, there we see a list of export formats, each one specifying the source, so you can see here that a drawing will export to an svg, a jpg, a png, or a pdf. CLAUDIO: That's the native Google Docs drawing, right? ALI: Exactly right. And then, likewise, a native Google document that can export to OpenOffice, Word, HTML obviously, a rich text, a plain text, or a PDF. So this is fairly predictable, but it's really worth looking at this feed so you can know what kind of files are going to be able to be exported from the native documents. Pretty useful, I think, so you can display the right thing to the user. CLAUDIO: What other information do we get from this feed? One question we often get is, how do I know how much disk space I have on Google Drive, and how much of that disk space is available? ALI: So apart from metadata about things the user can do, there's also metadata about the account. It's kind of a miscellaneous feed with the information that you need. And there are some quota fields, as well. So the first one here is quotaBytesTotal. That's how much total quota the user has. In this case, it's Claudio. How much of the quota is being used, which is a small amount. And how much is used in trash? And this helps you to, perhaps, display to the user that they're running out of quota. Or if the user in your application wants to upload a huge file, well, you can predict that there's not enough quota to upload that file. So you can say, no, I'm not going to perform this operation. Delete some files or buy some more quota. CLAUDIO: And the value for the quota used by files in trash can be useful for you to know anytime how much disk space you can recover without deleting any important file. So you know that all of those files were deleted by the users, so if you empty the trash, you just recovered some space and only lose non-important things. ALI: So let's go through some of these other ones because they are kind of interesting for highlighting features of the API. So here I've got what is a root folder ID. Can you tell us a bit about the root folder and what the root folder ID would be? CLAUDIO: Oh, yes. So in Drive, files can be organized in different folders. And a single file can have multiple parents, which we call folders. And a folder, of course, could have multiple children. And so when you try to draw the structure of all files in Google Drive, this structure would look like a tree. And, of course, as all trees, at the top of it there would be a root folder that we want to be always available for developers. So we have-- the root folder is a folder like any other folder. So it has an ID. It is actually a file like all other folders. But at any time if you want to know how to get the content of the root folder, if you want to get some specific information about the root folder, you can access that by using this ID. We also added some convenience methods to do that. And actually, we added an alias for the root folders. If you don't want to know or if you don't want to check what the ID for the root folder is, you can always refer to it using the string root, which is quite easy to remember. ALI: So you have a choice there which one you want to use. So thanks for explaining that. And I think this will conveniently get us on to the next thing we want to talk about. What's the largest change ID? CLAUDIO: So we have this other feed that I briefly mentioned earlier, which is called the changes feed. With the changes feed-- what the changes feed contains is a list of entries. And each entry represents some changes to the documents list you have. So let's say you want to synchronize your local files with the files in Google Drive. Instead of having to download all your files and check each of them with your local copy, you can simply synchronize once by downloading all the files, sorting the change ID corresponding to that moment in time when you downloaded all the files, and then only check the Changes feed, which will tell you something like on the change ID x, a new file was added. On change x plus 1, this file has been deleted or this file has changed its metadata or its content. ALI: Shall we look? CLAUDIO: Yeah. Let's have a look at what the Changes feed looks like. ALI: So back again we'll look at the available feeds. You don't ever need to remember these URIs, of course. You just need to know where to find it in-- CLAUDIO: They're also pretty easy to remember in case you want to, because they all have the same RESTful structure. So they all start with www.googleapis.com slash the name of the API, which is drive, slash the version which is v2 since Google I/O, and then slash the name of the feed, in this case is going to be change. ALI: With any additional query parameters or path parameters, but this feed doesn't have any. So, again, the Change feed is read-only. So I've done a Get there. And this time I get a list of drive changes, a drive change list. And you can see them here. So as Claudio was saying, each one-- each change has an ID. CLAUDIO: We should say it's increasing. It's an integer, it's a monotonic increasing integer. So you can always trust that the new ones will be greater than the previous ones. ALI: It's actually stored as a string, but there we go. And then the file that the change referred to. So that's by the file ID. Now, here is where we have a choice of how we behave, how we were return with this field. So a file could be deleted. Now, if it's being deleted, obviously we don't return the file data, because that data doesn't exist anymore. So the change itself describes at the top level whether it refers to a delete operation or a modify operation. And if it hasn't been deleted, ie deleted is set to false, we also have the entire file data in the feed here. CLAUDIO: By the entire file they mean all the metadata, right? We don't return the content. ALI: Of course. So the content, no. Just the file metadata is contained in here. CLAUDIO: This is consistent with what we always do when retrieving the list of files. We never return the content together with the metadata. We return the link to the content and then you have to download it. Because remember, the metadata is very small, so you can always get it, but the content can be pretty big. A file in Google Drive can be up to 10 gigabytes, so we don't want to return 100 gigabytes every time you want to know the list of files you have. ALI: Exactly. So Claudio, tell me why there's only one file in this list of changes. CLAUDIO: Because we only changed one file. ALI: We only changed one file. OK. That's it. If we look at the actual file itself, it was a Google Docs letter to the employees. CLAUDIO: Oh yeah. ALI: Good one. So here you can see the ID Claudio was talking about, and that refers also to the largest change ID that we've-- CLAUDIO: Let's say you synchronize your local status with this change, which is number 1620, I think, if I can read it. So next time, we can go to the next-- starting from the largest change ID, which is 2533, plus 1. ALI: Plus 1. Do you remember what the query parametere is? CLAUDIO: Nope. ALI: No, neither do I. CLAUDIO: It's [? not in any of ?] the documentation. Whenever you request the changes feed, you can say, don't give me all of it, just give me everything starting from ID number. And so next time, you want to start from an ID number that is greater than that. OK, cool. I think that's perfect. I think there's only one question left, which is, how do we get this? ALI: How do we get it? CLAUDIO: Yeah. ALI: Well, you just go to the website, code.google.com/ oauthplayground, and you can just start using it immediately. If you have Google Drive-- if you use Google Drive, then you can also go to the Chrome Web Store and install the OAuth 2.0 Google Drive application that is responsible for this functionality where you can open a file directly. OK. So that's in-- well, we'll add the URL somewhere so you can look at it when you're looking at this. CLAUDIO: Perfect. Thank you very much, Ali. ALI: OK. Thank you, Claudio. And thanks for watching. Take care.