Trang này được dịch bởi Cloud Translation API.

Bắt đầu

Tài liệu này cung cấp tất cả thông tin cơ bản mà bạn cần để bắt đầu sử dụng thư viện. Bài viết này trình bày các khái niệm về thư viện, đưa ra ví dụ cho nhiều trường hợp sử dụng và cung cấp đường liên kết đến nhiều thông tin hơn.

Thiết lập

Bạn cần hoàn thành một số bước thiết lập trước khi có thể sử dụng thư viện này:

Nếu bạn chưa có Tài khoản Google, hãy đăng ký.
Nếu bạn chưa từng tạo dự án Bảng điều khiển API của Google, hãy đọc trang Quản lý dự án và tạo một dự án trong Bảng điều khiển API của Google.
Cài đặt gói NuGet mà bạn muốn sử dụng.

Xác thực và uỷ quyền

Bạn cần nắm được kiến thức cơ bản về cách chúng tôi xử lý việc xác thực và uỷ quyền API. Tất cả lệnh gọi API đều phải sử dụng quyền truy cập đơn giản hoặc quyền được ủy quyền (được định nghĩa bên dưới). Nhiều phương thức API yêu cầu quyền truy cập được cấp phép, nhưng một số phương thức có thể sử dụng một trong hai phương pháp này. Một số phương thức API có thể sử dụng cách xử lý khác nhau, tuỳ thuộc vào việc bạn sử dụng quyền truy cập đơn giản hay quyền được cấp phép. Hãy xem tài liệu về phương pháp API để xác định loại quyền truy cập thích hợp.

1. Truy cập API đơn giản (khóa API)

Những lệnh gọi API này không truy cập vào bất kỳ dữ liệu riêng tư nào của người dùng. Ứng dụng của bạn phải tự xác thực dưới dạng một ứng dụng thuộc dự án Google API Console. Đây là dữ liệu cần thiết để đo lường mức sử dụng dự án cho các mục đích kế toán.

Khoá API: Để xác thực ứng dụng của bạn, hãy sử dụng khoá API cho dự án API Console. Mọi lệnh gọi truy cập đơn giản mà ứng dụng của bạn thực hiện phải bao gồm khóa này.

2. Truy cập API được ủy quyền (OAuth 2.0)

Những lệnh gọi API này truy cập vào dữ liệu riêng tư của người dùng. Trước khi bạn có thể gọi chúng, người dùng có quyền truy cập vào dữ liệu riêng tư phải cấp quyền truy cập cho ứng dụng của bạn. Do đó, ứng dụng của bạn phải được xác thực, người dùng phải cấp quyền truy cập cho ứng dụng của bạn, đồng thời người dùng đó phải được xác thực để cấp quyền truy cập đó. Bạn có thể thực hiện tất cả thao tác này bằng OAuth 2.0 và các thư viện viết cho khoá này.

Phạm vi: Mỗi API xác định một hoặc nhiều phạm vi khai báo một tập hợp thao tác được phép. Ví dụ: một API có thể có phạm vi chỉ đọc và phạm vi đọc/ghi. Khi ứng dụng của bạn yêu cầu quyền truy cập vào dữ liệu người dùng, yêu cầu đó phải bao gồm một hoặc nhiều phạm vi. Người dùng cần phê duyệt phạm vi truy cập mà ứng dụng của bạn đang yêu cầu.

Làm mới và truy cập mã thông báo: Khi người dùng cấp cho ứng dụng của bạn quyền truy cập, máy chủ uỷ quyền OAuth 2.0 sẽ cung cấp cho ứng dụng của bạn mã thông báo làm mới và truy cập. Các mã thông báo này chỉ hợp lệ đối với phạm vi được yêu cầu. Ứng dụng của bạn sử dụng mã truy cập để cho phép các lệnh gọi API. Mã truy cập sẽ hết hạn, nhưng mã thông báo làm mới thì không. Ứng dụng có thể sử dụng mã làm mới để lấy mã truy cập mới.

Mã ứng dụng khách và mật khẩu ứng dụng khách: Các chuỗi này nhận dạng riêng ứng dụng của bạn và dùng để lấy mã thông báo. Chúng được tạo cho dự án của bạn trên Bảng điều khiển API. Có ba loại mã ứng dụng khách, nên bạn hãy nhớ lấy loại mã chính xác cho ứng dụng của mình:

Mã ứng dụng khách ứng dụng web
ID ứng dụng khách đã cài đặt
Mã khách hàng của Tài khoản dịch vụ

Ví dụ

Trong phần này, có ví dụ về cách sử dụng API đơn giản mà không được phép. Để biết thêm thông tin về lệnh gọi ủy quyền, hãy xem trang OAuth 2.0 cho .NET.

Ví dụ về API đơn giản

Ví dụ này sử dụng quyền truy cập API đơn giản cho một ứng dụng dòng lệnh. API này sẽ gọi Google Discovery API để liệt kê tất cả API của Google.

Ví dụ: thiết lập

Nhận khoá API đơn giản. Để tìm khoá API của ứng dụng, hãy làm như sau:

Mở trang Thông tin xác thực trong Bảng điều khiển API.
API này hỗ trợ hai loại thông tin đăng nhập. Tạo thông tin xác thực phù hợp với dự án của bạn:
- OAuth 2.0: Bất cứ khi nào ứng dụng yêu cầu dữ liệu riêng tư của người dùng, ứng dụng đó phải gửi mã thông báo OAuth 2.0 cùng với yêu cầu đó. Trước tiên, ứng dụng của bạn sẽ gửi một mã ứng dụng và có thể là một mã bí mật của ứng dụng để lấy mã thông báo. Bạn có thể tạo thông tin xác thực OAuth 2.0 cho ứng dụng web, tài khoản dịch vụ hoặc ứng dụng đã cài đặt.
  
  Để biết thêm thông tin, hãy xem tài liệu về OAuth 2.0.
- Khoá API: Yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi khoá API. Khoá này xác định dự án của bạn và cung cấp quyền truy cập vào API, hạn mức và báo cáo.
  
  API hỗ trợ một số loại quy định hạn chế đối với khoá API. Nếu khoá API bạn cần chưa tồn tại, hãy tạo khoá API trong Bảng điều khiển bằng cách nhấp vào Tạo thông tin xác thực > khoá API. Bạn có thể hạn chế khoá trước khi sử dụng trong bản phát hành chính thức bằng cách nhấp vào Hạn chế khoá rồi chọn một trong các Hạn chế.

Để bảo mật khoá API, hãy làm theo các phương pháp hay nhất để sử dụng khoá API một cách an toàn.

Mã ví dụ

using System;
using System.Threading.Tasks;

using Google.Apis.Discovery.v1;
using Google.Apis.Discovery.v1.Data;
using Google.Apis.Services;

namespace Discovery.ListAPIs
{
    /// <summary>
    /// This example uses the discovery API to list all APIs in the discovery repository.
    /// https://developers.google.com/discovery/v1/using.
    /// <summary>
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Discovery API Sample");
            Console.WriteLine("====================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            // Create the service.
            var service = new DiscoveryService(new BaseClientService.Initializer
                {
                    ApplicationName = "Discovery Sample",
                    ApiKey="[YOUR_API_KEY_HERE]",
                });

            // Run the request.
            Console.WriteLine("Executing a list request...");
            var result = await service.Apis.List().ExecuteAsync();

            // Display the results.
            if (result.Items != null)
            {
                foreach (DirectoryList.ItemsData api in result.Items)
                {
                    Console.WriteLine(api.Id + " - " + api.Title);
                }
            }
        }
    }
}

Mẹo sử dụng khoá API:

Để sử dụng một dịch vụ cụ thể, bạn phải thêm tệp tham chiếu đến dịch vụ đó. Ví dụ: nếu muốn sử dụng API Tasks, bạn nên cài đặt gói NuGet của gói đó là Google.Apis.Tasks.v1.
Để tạo một thực thể của dịch vụ, chỉ cần gọi hàm khởi tạo của dịch vụ đó. Ví dụ: new TasksService(new BaseClientService.Initializer {...});".
Tất cả các phương thức của một dịch vụ đều nằm trên các tài nguyên riêng lẻ trên chính đối tượng dịch vụ đó. Dịch vụ Khám phá có tài nguyên Apis, chứa phương thức List. Khi bạn gọi service.Apis.List(..), một đối tượng yêu cầu nhắm mục tiêu phương thức này sẽ được trả về.
Để thực thi một yêu cầu, hãy gọi phương thức Execute() hoặc ExecuteAsyc() trên một yêu cầu.
Đặt khoá API bằng thuộc tính ApiKey trên phiên bản BaseClientService.Initializer.

Tìm thông tin về các API

Trang API được hỗ trợ liệt kê tất cả các API có thể truy cập được bằng thư viện này cũng như các đường liên kết đến tài liệu.

Bạn cũng có thể sử dụng APIs Explorer để duyệt xem các API, liệt kê các phương thức có sẵn và thậm chí là thử các lệnh gọi API trên trình duyệt.