# Bắt đầu nhanh

Chạy lượt tìm kiếm Google đầu tiên và nhận kết quả có cấu trúc cho ứng dụng hoặc tác nhân AI của bạn.

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/guides/quickstart
Xem lại: 2026-11-04 by FlashData

<a id="agent"></a>

## Bắt đầu với tác nhân AI

Gửi câu lệnh này cho tác nhân có quyền dùng terminal. Tác nhân sẽ thiết lập FlashData và chạy một lượt tìm kiếm.

### Câu lệnh thiết lập và tác vụ đầu tiên

```text
Đọc https://flashdata.dev/auth.md và làm theo hướng dẫn thiết lập FlashData cho môi trường này. Tái sử dụng quyền truy cập hiện có; nếu chưa có, chỉ bắt đầu một lần dùng thử khi đủ điều kiện. Tìm "battery recycling research" trên Google với tối đa năm kết quả. Trả về tiêu đề nguồn, URL và tín dụng thực tế đã dùng. Giữ thông tin xác thực trong bộ lưu trữ được bảo vệ, không đưa vào chat. Nếu truy cập bị chặn, hãy báo bước tiếp theo thay vì tạo lần dùng thử khác.
```

- [Thiết lập MCP](https://flashdata.dev/vi/docs/integrations/mcp-clients/reference.md)
- [Kỹ năng của tác nhân](https://flashdata.dev/vi/docs/guides/agent-skill/reference.md)

<a id="application"></a>

## Thực hiện lệnh gọi API đầu tiên

Muốn tự viết mã? Làm theo ba bước sau trong terminal.


<a id="api-key"></a>

### Lấy khóa API

Tạo tài khoản, xác minh email rồi tạo khóa có quyền Google Search. Nếu đã có khóa phù hợp, hãy dùng lại.

Chạy trong terminal và dán khóa vào lời nhắc nhập ẩn. Bỏ qua nếu FLASHDATA_API_KEY đã được đặt.

#### Bash

##### Đặt khóa

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Đặt khóa

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Tạo tài khoản](https://flashdata.dev/signup)
- [Mở API Keys](https://flashdata.dev/app/api-keys)

<a id="request"></a>

### Chạy tìm kiếm

Chọn ngôn ngữ và chạy ví dụ trong cùng terminal. Mỗi lần chạy sẽ gửi một lượt tìm kiếm.

#### Python

Python 3.10+ · Lưu ví dụ thành quickstart.py.

##### Cài đặt

```bash
python -m pip install "flashdata==1.1.0"
```

##### quickstart.py

```python
import json
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.search("battery recycling research", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    print(json.dumps(response, indent=2))
```

##### Chạy

```bash
python quickstart.py
```


#### TypeScript

Node.js 22.18+ · Bắt đầu trong thư mục trống và lưu quickstart.mts.

##### Thiết lập

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mts

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### Chạy

```bash
node quickstart.mts
```


#### JavaScript

Node.js 22+ · Bắt đầu trong thư mục trống và lưu quickstart.mjs.

##### Thiết lập

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mjs

```javascript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### Chạy

```bash
node quickstart.mjs
```


#### Go

Go 1.25+ · Bắt đầu trong thư mục trống và lưu main.go. Bỏ qua go mod init nếu mô-đun đã tồn tại.

##### Thiết lập

```bash
go mod init example.com/flashdata-quickstart
go get github.com/flashdatadev/flashdata-go@v1.1.0
```

##### main.go

```go
package main

import (
    "context"
    "encoding/json"
    "log"
    "os"
    "time"

    flashdata "github.com/flashdatadev/flashdata-go"
)

func main() {
    key := os.Getenv("FLASHDATA_API_KEY")
    if key == "" {
        log.Fatal("Set FLASHDATA_API_KEY through your server's secret manager.")
    }
    client, err := flashdata.New(flashdata.Options{APIKey: key})
    if err != nil {
        log.Fatal(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()
    result, err := client.Google.Search(ctx, flashdata.GoogleSearchInput{
        Query: "battery recycling research",
        Params: &flashdata.GoogleSearchParams{Num: flashdata.Ptr(int64(5))},
    })
    if err != nil {
        // Do not automatically resubmit an uncertain paid request.
        log.Fatal(err)
    }
    if err := json.NewEncoder(os.Stdout).Encode(result); err != nil {
        log.Fatal(err)
    }
    if result.Status != "done" {
        log.Fatalf("Search did not complete: %s", result.Status)
    }
}
```

##### Chạy

```bash
go run .
```


#### HTTP API

Không cần SDK. Chạy lệnh Bash / cURL 7.76+ hoặc lệnh PowerShell 7.

##### Bash / cURL

```bash
curl --fail-with-body --silent --show-error \
  --request POST https://data.flashdata.dev/v1/queries/realtime \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
```

##### PowerShell 7

```powershell
$flashdataRequest = '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
$flashdataResult = Invoke-RestMethod -Method Post -Uri 'https://data.flashdata.dev/v1/queries/realtime' -Headers @{ 'X-API-Key' = $env:FLASHDATA_API_KEY } -ContentType 'application/json' -Body $flashdataRequest
$flashdataResult | ConvertTo-Json -Depth 20
```


- [Kiểm tra kết quả bên dưới](https://flashdata.dev/vi/docs/guides/quickstart/reference.md#result)

<a id="result"></a>

### Kiểm tra kết quả

Phản hồi thành công có status: done. Nguồn nằm trong results[].organic và tín dụng đã tính nằm trong usage.credits.

#### Phản hồi mẫu (rút gọn)

```json
{
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  }
}
```

- [Cải thiện tìm kiếm](https://flashdata.dev/vi/docs/guides/google-search-guide/reference.md)
- [Thử YouTube Data](https://flashdata.dev/vi/docs/guides/youtube-data-guide/reference.md)
- [Thiết lập API và khắc phục sự cố](https://flashdata.dev/vi/docs/guides/http-quickstart/reference.md)

<a id="console"></a>

## Thử bảng điều khiển

1. Tạo tài khoản hoặc đăng nhập. Hoàn tất xác minh email và các bước thiết lập tài khoản được hiển thị trong bảng điều khiển.
2. Mở Google Search, chọn nguồn Google Search và chế độ Realtime, rồi nhập battery recycling research. Mở Additional parameters và đặt Page size (num) thành 5.
3. Kiểm tra yêu cầu hiển thị và tín dụng khả dụng, sau đó chạy tìm kiếm một lần.
4. Kiểm tra phản hồi và mức sử dụng. Mở nguồn được trả về để xác minh nội dung trước khi trích dẫn thông tin ngoài đoạn trích.

- [Tạo tài khoản](https://flashdata.dev/signup)
- [Mở Google Search](https://flashdata.dev/app/google-search)

<a id="next"></a>

## Phát triển từ kết quả đầu tiên

- [Tìm kiếm bằng bộ lọc](https://flashdata.dev/vi/docs/guides/google-search-guide/reference.md)
- [Khám phá dữ liệu YouTube](https://flashdata.dev/vi/docs/guides/youtube-data-guide/reference.md)
- [Thêm tìm kiếm vào ứng dụng](https://flashdata.dev/vi/docs/guides/search-in-an-app/reference.md)

<a id="troubleshooting"></a>

## Nếu yêu cầu đầu tiên thất bại

| Hiện tượng | Cách xử lý |
| --- | --- |
| Thiếu FLASHDATA_API_KEY | Đặt khóa trong cùng terminal hoặc môi trường chạy ví dụ. Các đoạn mã này không đọc tệp .env. |
| 401 / 403 | Kiểm tra khóa hoặc kết nối đang hoạt động và có quyền google_search. |
| 402 | Kiểm tra tín dụng khả dụng trong Billing. Liên kết lượt dùng thử hiện có với tài khoản nếu cần quyền của chủ sở hữu. |
| 429 | Tuân theo Retry-After. Giữ nguyên danh tính và bằng chứng đăng ký; không tạo lượt dùng thử khác. |
| Hết thời gian chờ hoặc chưa rõ trạng thái gửi | Kiểm tra lần chạy hiện có trước khi thử lại. Người dùng CLI cần giữ nguyên hồ sơ và ID lần chạy; người dùng SDK/API cần lưu ID tác vụ hoặc yêu cầu được trả về. |

