データクラウド「Snowflake」には、「Snowflake SQL REST API」と呼ばれるAPIが用意されています。「Snowflake SQL REST API」を利用することで、外部アプリケーション等からSnowflakeへSQLステートメントを送信したり、ストアドプロシージャを作成/実行したりできます。これはつまり、外部アプリケーション等から「Snowflake SQL REST API」を介して、Snowflakeのデータにアクセスしたり、データの更新をしたりできることを意味します。

本ブログ記事では、「Snowflake SQL REST API」について、次の3つの観点からわかりやすく解説します。

•  何ができるのか？（どのようなSQLが発行できるのか？）
•  Snowflakeへの認証はどのようにおこなわれるのか？
•  エラーの場合はどうなるのか？

これらのポイントをおさえ、「Snowflake SQL REST API」を上手に活用しましょう。

Snowflake SQL REST API とは？

「Snowflake SQL REST API」は、Snowflakeのデータにアクセスするために使用できる、REST形式のAPIです。「Snowflake SQL REST API」でできることは、次の４点です。

• Snowflakeで実行するSQLステートメントの送信
• SQLステートメントの実行ステータスの確認
• SQLステートメントの実行のキャンセル
• クエリ結果のフェッチ

「Snowflake SQL REST API」の最大の特徴は、標準クエリとDDL（データ定義言語） / DML（データ操作言語）のステートメントを実行し、その結果を取得できることです。
つまり、APIを利用することで、Snowflake内のデータの参照/更新/削除や、オブジェクト（テーブル/プロシージャ など）の作成/削除まで、さまざまな操作をおこなうことができます。
このことを踏まえ、SnowflakeのAPIの利点は、次のように考えられます。

• Snowflakeの標準機能であるため、APIを利用するための特別な準備作業は必要なく、すぐ利用開始できる
• 一般的なクエリやDDL/DMLの知識があれば利用できるため、利用者の学習コストが軽減できる
• Snowflakeのユーザー/ロールによる権限管理により、APIの権限も制御できるため、権限の一元管理が可能（権限と認証については次章で解説します）

以上より、外部アプリケーションからSnowflakeのデータへアクセスする手段のひとつとして、「Snowflake SQL REST API」は、非常に有用な機能といえます。

Snowflake SQL REST API の認証方式とは？

前章で記載したとおり、「Snowflake SQL REST API」を利用することで、データの参照/更新/削除 等の操作をおこなうことができます。そのため、APIの用途や目的に応じて、APIで許可する操作の権限を正しく制御する必要があります。
では、API利用時には、どのような方法で認証をおこない、権限を制御するのでしょうか。

API利用時には、基本認証（ユーザー名とパスワード）の代わりに、「キーペア認証」または「OAuth認証」を利用し、認証セキュリティを強化することができます。

まずは、「キーペア認証」について説明します。
「キーペア認証」は、公開鍵/秘密鍵のペアを作成し、公開鍵とSnowflakeのユーザーを紐づけます。APIを利用するアプリケーションは、この公開鍵をもとに、「JSON Web トークン（JWT）」を生成します。そして、APIの送信リクエストで、「JWT」をヘッダ情報として設定することで、ユーザーの認証をおこないます。
このとき、「JWT」に紐づくSnowflakeユーザーがオブジェクト（DB/スキーマ/テーブル/プロシージャ 等）に対して持っている権限に基づいて、APIで指定したステートメントが実行されます。そのため、Snowflakeのユーザー/ロールによる権限管理により、API実行時の権限を制御できるといえます。
「キーペア認証」では、Snowflakeの管理者はAPIを利用するユーザーのみに鍵を設定/配布すればよいため、ガバナンスの観点からもAPIの利用者を管理しやすいというメリットがあります。

次に、「OAuth認証」を紹介します。
「OAuth認証」の場合、「Snowflake OAuth」または「外部OAuth」を利用することができます。Snowflakeは、「Okta」や「Microsoft Azure AD」等の外部認証サービスをサポートしています。

Snowflake SQL REST API でSQLステートメントを実行してみよう

ここまで、「Snowflake SQL REST API」の概要や認証について解説して参りましたが、説明文だけでは中々イメージがつきにくいかと思います。そこで本章では、実際に「Snowflake SQL REST API」を実行する方法についてご紹介します。

「Snowflake SQL REST API」は、REST形式であり、アプリケーションの開発言語に合わせたフォーマットで実行します。

例えば、「Curl」で呼び出す場合、次のURLのSnowflake提供ドキュメントからサンプルをご参照いただけます。
https://docs.snowflake.com/ja/developer-guide/sql-api/submitting-requests#example-of-a-request

前述のURLのサンプルにあるように、ヘッダ情報として認証方式や認証トークンを指定し、実行したいSQLステートメントをパラメータとして引き渡します。

また、「Snowflake SQL REST API」を実行した際、その結果はどのように返却されるでしょうか？
「Snowflake SQL REST API」を実行した際、アプリケーションにはHTTPコードと結果セットが返却されます。
結果セットに関する記述は、次のURLのSnowflake社提供ドキュメントを参照してください。
https://docs.snowflake.com/ja/developer-guide/sql-api/handling-responses#getting-the-results-from-the-response

結果セットには、「結果ステータス」、「データ」、「メタ情報」、「パーティション情報」の要素が含まれます。
「結果ステータス」には、API実行の成功/失敗のステータスや、メッセージが含まれます。
結果ステータスが成功の場合、SQLステートメントの結果は、「データ」として返されます。
さらに、「メタ情報」には、データのカラム名やデータ型の情報が含まれています。
また、返却するデータ量が多い場合は、データはパーティションに分割されます。このパーティションに関する情報も結果セットの中に含まれています。
APIを実行したアプリケーションは、これら結果セット内の各要素を組み合わせて、データを処理することができる、ということを抑えておきましょう。

最後に、「Snowflake SQL REST API」のチュートリアルをご紹介します。
チュートリアルはSnowflake社が提供しており、このチュートリアルを通して、APIの実行や結果セットの確認を行うことができます。是非、一度お試しください。
https://quickstarts.snowflake.com/guide/getting_started_snowflake_sql_api/index.html#0

なお、無料トライアルでも、「Snowflake SQL REST API」はご利用いただけます。
Snowflakeの無料トライアルのはじめ方は、こちらのブログをご参照ください。
https://itsol.dentsusoken.com/snowflake/blog/snowflake-trial-vol-010-3644/ 

Snowflake SQL REST API におけるエラーハンドリング

「Snowflake SQL REST API」を実行した際、SQLステートメントのエラーや認証エラー 等、さまざまなエラーが発生する可能性があります。APIを実行したプログラムは、どのようにこのエラーを検知し、その後の処理をおこなえばよいでしょうか。

前述の通り、「Snowflake SQL REST API」を実行した際、アプリケーションにはHTTPコードと結果セットが返却されます。
APIが「成功したか」、「失敗したのか」、「失敗した場合、その原因はどこにあるのか」は、返却されるHTTPコードで大まかに判別することができます。返却されるHTTPコードをもとに、エラーの対策をおこないましょう。
次の表は、返却されるHTTPコードの一部をご紹介したものです。

「Snowflake SQL REST API」実行時に返却されるHTTPコード（一部抜粋）

その他のHTTPコードについては、次のURLのSnowflake社提供ドキュメントをご参照ください。
https://docs.snowflake.com/ja/developer-guide/sql-api/reference#response-codes-for-all-operations

まとめ

さてここまで、「Snowflake SQL REST API」について解説して参りました。
SnowflakeのAPIについて、次のポイントをご理解いただけたのではないでしょうか？

• Snowflakeの標準機能であり、すぐに利用できる
• APIでは、標準クエリとDDL（データ定義言語） / DML（データ操作言語）のステートメントを実行できる
• API実行時、「キーペア認証」または「OAuth認証」を利用し、認証セキュリティを強化できる
• API実行時、返却されるHTTPコードを利用してエラーハンドリングができる
• APIのチュートリアルがSnowflake社から提供されており、無料トライアル環境でもAPIの実行ができる

本ブログ記事が、データクラウド「Snowflake」の特徴的な機能のひとつ、「Snowflake SQL REST API」のご理解につながり、少しでも皆様のお役に立ちましたら幸いです。

弊社は、データマネジメントの専門家として、お客様のデータ一元管理やデータ活用における戦略策定、データドリブン経営の実現に向けた真の“使える”データマネジメント基盤構築のご支援をしております。
データ分析基盤の豊富な構築実績に基づくノウハウを体系化したサービスをご提供しておりますので、データ活用でお悩みの際は、是非、弊社までお声掛けください。

◆ お問い合わせページ：https://itsol.dentsusoken.com/snowflake/inquiry/

＊本記事は、2023年12月1日時点の情報を基に作成しています。
製品・サービスに関する詳しいお問い合わせは、電通総研のWebサイトからお問い合わせください。