diff options
author | alexv-smirnov <alexv-smirnov@yandex-team.ru> | 2022-02-23 21:00:31 +0300 |
---|---|---|
committer | alexv-smirnov <alexv-smirnov@yandex-team.ru> | 2022-02-23 21:00:31 +0300 |
commit | 9f906d188714c5bd1dfc2d29117ba02ee1859730 (patch) | |
tree | e38ebbbd8ed31c759cc13698c1af56803f6e1487 | |
parent | 7b3cdd1a3eafcc26aeac321c91eb293e6abd4d03 (diff) | |
download | ydb-9f906d188714c5bd1dfc2d29117ba02ee1859730.tar.gz |
ydb docs fixing rebase artifacts
ref:9b04a6a91d292891214ad341e4b503ef0988cf77
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 |