aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authoralexv-smirnov <alexv-smirnov@yandex-team.ru>2022-02-23 21:00:31 +0300
committeralexv-smirnov <alexv-smirnov@yandex-team.ru>2022-02-23 21:00:31 +0300
commit9f906d188714c5bd1dfc2d29117ba02ee1859730 (patch)
treee38ebbbd8ed31c759cc13698c1af56803f6e1487
parent7b3cdd1a3eafcc26aeac321c91eb293e6abd4d03 (diff)
downloadydb-9f906d188714c5bd1dfc2d29117ba02ee1859730.tar.gz
ydb docs fixing rebase artifacts
ref:9b04a6a91d292891214ad341e4b503ef0988cf77
-rw-r--r--ydb/docs/ru/core/concepts/_includes/connect.md13
-rw-r--r--ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md4
-rw-r--r--ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md261
3 files changed, 0 insertions, 278 deletions
diff --git a/ydb/docs/ru/core/concepts/_includes/connect.md b/ydb/docs/ru/core/concepts/_includes/connect.md
index 6e18a6a8c1..06a774d35c 100644
--- a/ydb/docs/ru/core/concepts/_includes/connect.md
+++ b/ydb/docs/ru/core/concepts/_includes/connect.md
@@ -47,30 +47,17 @@
При выборе режима аутентификации среди поддерживаемых сервером и окружением, следует руководствоваться следующими рекомендациями:
-<<<<<<< ydb/docs/ru/core/concepts/_includes/connect.md
-- **Anonymous** обычно применяется на самостоятельно разворачиваемых локальных кластерах YDB, недоступных по сети
-- **Access Token** применяется при отсутствии поддержки других режимов на стороне сервера, или в настроечных/отладочных целях. Он не требует взаимодействий клиента с IAM. Однако, если IAM поддерживает API для ротации токенов, то обычно выдаваемые таким IAM фиксированные токены имеют короткий срок жизни, что вынуждает регулярно обновлять их в IAM вручную заново.
-=======
- **Anonymous** обычно применяется на самостоятельно разворачиваемых локальных кластерах {{ ydb-short-name }}, недоступных по сети
- **Access Token** применяется при отсутствии поддержки других режимов на стороне сервера, или в настроечных/отладочных целях. Он не требует взаимодействий клиента с IAM. Однако, если IAM поддерживает API для ротации токенов, то обычно выдываемые таким IAM фиксированные токены имеют короткий срок жизни, что вынуждает регулярно обновлять их в IAM вручную заново.
->>>>>>> ydb/docs/ru/core/concepts/_includes/connect.md
- **Refresh Token** может применяться при выполнении разовых ручных операций под персональной учетной записью, например, связанных с обслуживанием данных в БД, выполнением ad-hoc операций в CLI, или запусками приложений с рабочей станции. Такой токен можно получить вручную в IAM один раз на долгий срок, и сохранить в переменной окружения на личной рабочей станции для автоматического применения при запуске CLI без дополнительных параметров аутентификации.
- **Service Account Key** применяется в первую очередь для приложений, рассчитанных на эксплуатацию в окружениях, где поддерживается режим **Metadata**, при их тестировании вне таких окружений (например, на рабочей станции). Также он может применяться для приложений вне таких окружений, работая как аналог **Refresh Token** для сервисных учетных записей. В отличие от персональной учетной записи, объекты доступа и роли сервисной учетной записи могуть быть ограничены.
- **Metadata** применяется при разворачивании приложений в облаках. В настоящее время этот режим поддерживается на виртуальных машинах и в Cloud Functions Yandex.Cloud.
-<<<<<<< ydb/docs/ru/core/concepts/_includes/connect.md
-Токен для указания в параметрах может быть получен в системе IAM, с которой связана конкретная установка YDB. В частности, для сервиса YDB в Yandex.Cloud применяется Yandex.Passport OAuth и сервисные аккаунты Yandex.Cloud. При использовании YDB в корпоративных контекстах могут применяться стандартные для данной организации системы централизованной аутентификации.
-
-{% include [overlay/auth_choose.md](connect_overlay/auth_choose.md) %}
-
-При использовании режимов, предусматривающих обращение клиента YDB к IAM, дополнительно может быть задан URL IAM, предоставляющий API выдачи токенов. по умолчанию в существующих SDK и CLI производится попытка обращения к API IAM Yandex.Cloud, размещенному на `iam.api.cloud.yandex.net:443`.
-=======
Токен для указания в параметрах может быть получен в системе IAM, с которой связана конкретная установка {{ ydb-short-name }}. В частности, для сервиса {{ ydb-short-name }} в Yandex.Cloud применяется Yandex.Passport OAuth и севисные аккаунты Yandex.Cloud. При использовании {{ ydb-short-name }} в корпоративных контекстах могут применяться стандартные для данной организации системы централизованной аутентификации.
{% include [overlay/auth_choose.md](connect_overlay/auth_choose.md) %}
При использовании режимов, предусматривающих обращение клиента {{ ydb-short-name }} к IAM, дополнительно может быть задан URL IAM, предоставляющий API выдачи токенов. По-умолчанию в существующих SDK и CLI производится попытка обращения к API IAM Yandex.Cloud, размещенному на `iam.api.cloud.yandex.net:443`.
->>>>>>> ydb/docs/ru/core/concepts/_includes/connect.md
## Размещение базы данных {#database}
diff --git a/ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md b/ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md
index e2b5d97bb4..1e0b517aa8 100644
--- a/ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md
+++ b/ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md
@@ -15,11 +15,7 @@
### TOC (Table of Contents) - содержание
-<<<<<<< ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md
-TOC в документации YDB собирается из множества файлов, размещенных в директориях со статьями, которые иерархически включаются друг в друга директивой include. В результате каждый из этих файлов может быть переопределен по отдельности в адаптированной документации.
-=======
TOC в документации {{ ydb-short-name }} собирается из множества файлов, размещенных в директориях со статьями, которые иерархически включаются друг в друга директивой include. В результате, каждый из этих файлов может быть переопределен по-отдельности в адаптированной документации.
->>>>>>> ydb/docs/ru/core/how_to_edit_docs/_includes/customize.md
Как и для статей, для файлов TOC применяется подход с прокси, со следующей реализацией:
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md
index 8d71eee7ce..e69de29bb2 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md
@@ -1,261 +0,0 @@
-<<<<<<< ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md
-# Приложение на Go
-
-На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/basic), использующего [Go SDK](https://github.com/ydb-platform/ydb-go-sdk/v3) {{ ydb-short-name }}.
-
-{% include [addition.md](auxilary/addition.md) %}
-
-{% include [init.md](steps/01_init.md) %}
-
-Для работы с {{ ydb-short-name }} в `go` следует импортировать пакет драйвера `ydb-go-sdk`:
-
-```go
-import (
- // общие импорты
- "context"
- "path"
-
- // импорты пакетов ydb-go-sdk
- "github.com/ydb-platform/ydb-go-sdk/v3"
- "github.com/ydb-platform/ydb-go-sdk/v3/table" // для работы с table-сервисом
- "github.com/ydb-platform/ydb-go-sdk/v3/table/options" // для работы с table-сервисом
- "github.com/ydb-platform/ydb-go-sdk/v3/table/result" // для работы с table-сервисом
- "github.com/ydb-platform/ydb-go-sdk/v3/table/result/named" // для работы с table-сервисом
- "github.com/ydb-platform/ydb-go-sdk-auth-environ" // для аутентификации с использованием переменных окружения
- "github.com/ydb-platform/ydb-go-yc" // для работы с YDB в Яндекс Облаке
-)
-```
-
-Фрагмент кода приложения для инициализации драйвера:
-
-```go
-ctx := context.Background()
-// строка подключения
-dsn := "grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1g8skpblkos03malf3s/etn01f8gv9an9sedo9fu"
-// IAM-токен
-token := "t1.9euelZrOy8aVmZKJm5HGjceMkMeVj-..."
-// создаем объект подключения db, является входной точкой для сервисов YDB
-db, err := ydb.New(
- ctx,
- ydb.WithConnectionString(dsn),
-// yc.WithInternalCA(), // используем сертификаты Яндекс Облака
- ydb.WithAccessTokenCredentials(token), // аутентификация с помощью токена
-// ydb.WithAnonimousCredentials(token), // анонимная аутентификация (например, в docker ydb)
-// yc.WithMetadataCredentials(token), // аутентификация изнутри виртуальной машины в Яндекс Облаке или из Яндекс Функции
-// yc.WithServiceAccountKeyFileCredentials("~/.ydb/sa.json"), // аутентификация в Яндекс Облаке с помощью файла сервисного аккаунта
-// environ.WithEnvironCredentials(ctx), // аутентификация с использованием переменных окружения
-)
-if err != nil {
- // обработка ошибки подключения
-}
-// закрытие драйвера по окончании работы программы обязательно
-defer func() {
- _ = db.Close(ctx)
-}()
-```
-
-Объект `db` является входной точкой для работы с сервисами {{ ydb-short-name }}.
-Для работы сервисом таблиц следует использовать клиента table-сервиса `db.Table()`.
-Клиент table-сервиса предоставляет `API` для выполнения запросов над таблицами.
-Наиболее востребован метод `db.Table().Do(ctx, op)`, который реализует фоновое создание сессий и повторные попытки выполнить пользовательскую операцию `op`, в которую пользовательскому коду отдается подготовленная сессия.
-Сессия имеет исчерпывающее `API`, позволяющее выполнять `DDL`, `DML`, `DQL` и `TCL` запросы.
-
-{% include [steps/02_create_table.md](steps/02_create_table.md) %}
-
-Для создания таблиц используется метод `table.Session.CreateTable()`:
-
-```go
-err = db.Table().Do(
- ctx,
- func(ctx context.Context, s table.Session) (err error) {
- return s.CreateTable(ctx, path.Join(db.Name(), "series"),
- options.WithColumn("series_id", types.Optional(types.TypeUint64)),
- options.WithColumn("title", types.Optional(types.TypeUTF8)),
- options.WithColumn("series_info", types.Optional(types.TypeUTF8)),
- options.WithColumn("release_date", types.Optional(types.TypeDate)),
- options.WithColumn("comment", types.Optional(types.TypeUTF8)),
- options.WithPrimaryKeyColumn("series_id"),
- )
- },
-)
-if err != nil {
- // обработка ситуации, когда не удалось выполнить запрос
-}
-```
-
-С помощью метода `table.Session.DescribeTable()` можно вывести информацию о структуре таблицы и убедиться, что она успешно создалась:
-
-```go
-err = db.Table().Do(
- ctx,
- func(ctx context.Context, s table.Session) (err error) {
- desc, err := s.DescribeTable(ctx, path.Join(db.Name(), "series"))
- if err != nil {
- return
- }
- log.Printf("> describe table: %s\n", tableName)
- for _, c := range desc.Columns {
- log.Printf(" > column, name: %s, %s\n", c.Type, c.Name)
- }
- return
- },
-)
-if err != nil {
- // обработка ситуации, когда не удалось выполнить запрос
-}
-```
-
-{% include [steps/04_query_processing.md](steps/04_query_processing.md) %}
-
-Для выполнения YQL-запросов используется метод `table.Session.Execute()`.
-SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью структуры `table.TxControl`.
-
-```go
-var (
- readTx = table.TxControl(
- table.BeginTx(
- table.WithOnlineReadOnly(),
- ),
- table.CommitTx(),
- )
-)
-err := db.Table().Do(
- ctx,
- func(ctx context.Context, s table.Session) (err error) {
- var (
- res result.Result
- id *uint64 // указатель - для опциональных результатов
- title *string // указатель - для опциональных результатов
- date *time.Time // указатель - для опциональных результатов
- )
- _, res, err = s.Execute(
- ctx,
- readTx,
- `
- DECLARE $seriesID AS Uint64;
- SELECT
- series_id,
- title,
- release_date
- FROM
- series
- WHERE
- series_id = $seriesID;
- `,
- table.NewQueryParameters(
- table.ValueParam("$seriesID", types.Uint64Value(1)), // подстановка в условие запроса
- ),
- options.WithQueryCachePolicy(
- options.WithQueryCachePolicyKeepInCache(), // включаем серверный кэш скомпилированных запросов
- ),
- )
- if err != nil {
- return err
- }
- defer func() {
- _ = res.Close() // закрытие result'а обязательно
- }()
- log.Printf("> select_simple_transaction:\n")
- for res.NextResultSet(ctx) {
- for res.NextRow() {
- // в ScanNamed передаем имена колонок из строки сканирования,
- // адреса (и типы данных), куда следует присвоить результаты запроса
- err = res.ScanNamed(
- named.Optional("series_id", &id),
- named.Optional("title", &title),
- named.Optional("release_date", &date),
- )
- if err != nil {
- return err
- }
- log.Printf(
- " > %d %s %s\n",
- *id, *title, *date,
- )
- }
- }
- return res.Err()
- },
-)
-if err != nil {
- // обработка ошибки выполнения запроса
-}
-```
-
-{% include [scan_query.md](steps/08_scan_query.md) %}
-
-Для выполнения scan-запросов используется метод `table.Session.StreamExecuteScanQuery()`.
-
-```go
-var (
- query = `
- DECLARE $series AS List<UInt64>;
- SELECT series_id, season_id, title, first_aired
- FROM seasons
- WHERE series_id IN $series
- `
- res result.StreamResult
-)
-err = c.Do(
- ctx,
- func(ctx context.Context, s table.Session) (err error) {
- res, err = s.StreamExecuteScanQuery(ctx, query,
- table.NewQueryParameters(
- table.ValueParam("$series",
- types.ListValue(
- types.Uint64Value(1),
- types.Uint64Value(10),
- ),
- ),
- ),
- )
- if err != nil {
- return err
- }
- defer func() {
- _ = res.Close() // закрытие result'а обязательно
- }()
- var (
- seriesID uint64
- seasonID uint64
- title string
- date time.Time
- )
- log.Print("\n> scan_query_select:")
- for res.NextResultSet(ctx) {
- if err = res.Err(); err != nil {
- return err
- }
- for res.NextRow() {
- // named.OptionalOrDefault позволяет "развернуть" опциональные
- // результаты или использовать дефолтное значение типа go
- err = res.ScanNamed(
- named.OptionalOrDefault("series_id", &seriesID),
- named.OptionalOrDefault("season_id", &seasonID),
- named.OptionalOrDefault("title", &title),
- named.OptionalOrDefault("first_aired", &date),
- )
- if err != nil {
- return err
- }
- log.Printf("# Season, SeriesId: %d, SeasonId: %d, Title: %s, Air date: %s", seriesID, seasonID, title, date)
- }
- }
- return res.Err()
- },
-)
-if err != nil {
- // обработка ошибки выполнения запроса
-}
-```
-
-
-{% note info %}
-
-Разбор кода тестового приложения, использующего архивные версии Go SDK:
- - [github.com/yandex-cloud/ydb-go-sdk](https://github.com/yandex-cloud/ydb-go-sdk/tree/v1.5.1) доступен по [ссылке](../archive/example-go-v1.md),
- - [github.com/yandex-cloud/ydb-go-sdk/v2](https://github.com/yandex-cloud/ydb-go-sdk/tree/v2.11.2) доступен по [ссылке](../archive/example-go-v2.md).
-
-{% endnote %}
-=======
->>>>>>> ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md