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. Tài liệu này trình bày các khái niệm về thư viện, trình bày ví dụ cho nhiều trường hợp sử dụng và cung cấp các đường liên kết để tham khảo thêm thông tin.

Thiết lập

Bạn cần hoàn tất một số bước thiết lập để 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 trong Google API Console, hãy đọc trang Quản lý dự án và tạo dự án trong Google API Console.
Cài đặt gói NuGet mà bạn muốn xử lý.

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

Bạn cần hiểu rõ những thông tin cơ bản về cách xử lý quá trình 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 được cấp phép (đượ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 cách này. Một số phương thức API có thể sử dụng cả hai cách hoạt động theo cách khác nhau, tuỳ thuộc vào việc bạn sử dụng quyền truy cập đơn giản hay được cấp phép. Hãy xem tài liệu về phương thức của API để xác định loại quyền truy cập phù hợp.

1. Truy cập API đơn giản (khoá 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 là một ứng dụng thuộc dự án Google API Console của bạn. Dữ liệu này là cần thiết để đo lường mức sử dụng dự án cho 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 Bảng điều khiển API. Mọi lệnh gọi truy cập đơn giản mà ứng dụng của bạn thực hiện đều phải bao gồm khoá này.

2. Quyền truy cập vào API được cho phép (OAuth 2.0)

Các 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 các lệnh này, 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 vào ứ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 vào ứng dụng và phải xác thực người dùng để cấp quyền truy cập đó. Tất cả những điều này đều được thực hiện bằng OAuth 2.0 và các thư viện được viết cho nó.

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ụ: 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à mã truy cập: Khi người dùng cấp quyền truy cập vào ứng dụng của bạn, máy chủ uỷ quyền OAuth 2.0 sẽ cung cấp mã làm mới và mã truy cập cho ứng dụng của bạn. Các mã thông báo này chỉ hợp lệ cho phạm vi được yêu cầu. Ứng dụng của bạn dùng mã truy cập để cho phép thực hiện lệnh gọi API. Mã truy cập hết hạn, nhưng mã làm mới thì không. Ứng dụng của bạn có thể 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 duy nhất ứng dụng của bạn và được dùng để lấy mã thông báo. Các API này được tạo cho dự án của bạn trên Bảng điều khiển API. Có 3 loại mã ứng dụng khách, vì vậy, hãy nhớ chọn đúng loại cho ứng dụng của bạn:

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

Ví dụ

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

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

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

Thiết lập chẳng hạn

Lấy 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 xác thực. Tạo bất kỳ thông tin đăng nhập nào 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 kèm theo yêu cầu. Trước tiên, ứng dụng sẽ gửi một mã ứng dụng khách và có thể là mật khẩu ứng dụng khách để 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 API, hạn mức và báo cáo.
  
  API hỗ trợ một số loại hạn chế đối với khoá API. Nếu khoá API mà bạn cần chưa tồn tại, hãy tạo một 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 phiên bản chính thức bằng cách nhấp vào Restrict key (Hạn chế) rồi chọn một trong các hạn chế.

Để giữ an toàn cho 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 thông tin 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 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 từng tài nguyên riêng lẻ trên chính đối tượng dịch vụ. Dịch vụ Khám phá có một 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 đến 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() theo một yêu cầu.
Đặt khoá API bằng thuộc tính ApiKey trên thực thể BaseClientService.Initializer.

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

Trang API được hỗ trợ liệt kê tất cả API mà bạn có thể truy cập 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 (Trình khám phá API) để duyệt qua 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 của mình.